pythia-conventions

プロジェクトの規約を取り入れる

開始時に宣言：「pythia-conventions を使用します。まずスキーマからパターンを読み取ります。」

**フェーズ：**学習 → 質問 — スキーマから導き出し、ドキュメントと食い違う点を確認してから、設定を書きます

成熟したスキーマには、すでに規約が存在します。オブジェクト名、標準ドキュメント、またはシニア開発者の頭の中にあります。これらを2つのファイルにまとめます。ツールが書き込みのたびにチェックするパターンと、今後のすべてのエージェントセッションが書き込み前に読む説明文です。

鉄則

NO PATTERN WRITTEN DOWN BEFORE THE SCHEMA HAS AGREED WITH IT

既存のオブジェクトに一致しないパターンは、規約ではありません。 適用のたびに警告が出て、誰かが削除するまで続く推測にすぎません。

ワークフロー

1. データベースから実際の構造を読み取ります。記憶に頼ってはいけません。

   pythia conventions --scan
   

   すべてのオブジェクト名をトークン化し、タイプごとにパターンを提案します。ドキュメントが存在する場合でも、必ず実行してください。また、何千もの名前を自分でページ送りして確認してはいけません。そのためのコマンドであり、コンテキストは別のことに使うほうが有効です。

2. 開発者のドキュメントがあれば読みます。 基盤システムの標準、Wiki ページ、以前のプロジェクトのルールなどです。正規表現では表現できないものを探してください。呼び出し側のレイヤーが依存するパラメーターの接頭辞、すべてのクエリでフィルタリングが必要なカラム、トランザクションをコミットできる場所、標準とする日付や金額の表現などです。これらは説明文のほうに記載します。

3. 照合し、食い違いがあればその旨を伝えます。 ドキュメントは意図を示し、スキーマは事実を示します。ドキュメントのルールとスキーマが矛盾している場合、考えられるのは3つです。誰も従っていないルール、新しいコードにのみ適用されるルール、または報告すべき乖離です。どれなのか開発者に確認し、黙って判断してはいけません。

4. .pythia/conventions.json を作成します。 スキャン結果を出発点に、ドキュメントに合わせて絞り込みます。最初にひな形が必要なら、pythia conventions --init で空のファイル一式を作成できます。

5. 検証します。このスキルの要点はここにあります。

   pythia conventions --check
   

   タイプごとのカバレッジと、一致しない名前が報告されます。

   結果	意味
   すべての名前が一致する	パターンは実態に合っています。そのまま使います
   約90% 以上が一致し、少数の不一致がある	正当な例外です。手順6で列挙します
   90% 未満	パターンが間違っています。 スキーマではありません。パターンを広げるか分割してから、もう一度チェックします
   そのタイプのオブジェクトがない	未検証のルールです。そのタイプの新しいオブジェクトが想定される場合に限り、維持します

6. 例外とその理由を記録します。 意図的にルールから外れているオブジェクト、たとえば基盤プラットフォームから移行した名前や、名前が公開インターフェースの一部になっているレガシーなエントリーポイントなどです。警告を許容するよりも、名前を変更するコストのほうが高い理由を記載します。説明のない例外は、次の人に「修正」されてしまいます。

7. .pythia/conventions.md を作成します。 各ルールについて、ルールだけでなく、違反した場合のコストを記載します。「パラメーターの接頭辞は b_/a_ にする」は無視できますが、「呼び出し側のレイヤーは接頭辞でバインドするため、誤った接頭辞を使うとフィールドが気付かれないままバインド解除される」は無視できません。影響が明記されたルールは守られます。

LEAD のルールを機械的にチェックする：lint ブロック

名前に対する正規表現では表現できなくても、リンターでチェックできるルールは、conventions.json の naming の隣に記載します。以降、すべての pythia lint と適用プレビューでチェックされ、オートパイロットは error を適用しません。

"lint": {
  "rules": {"varchar2-byte-semantics": "error", "dbms-output": "off"},
  "require_comments": "error",
  "required_columns": ["CREATED_BY", "CREATED_AT"],
  "param_prefix": "^P_",
  "forbid": [{"id": "no-sysdate", "pattern": "\\bSYSDATE\\b",
              "message": "use SYSTIMESTAMP", "severity": "warning"}]
}

重要度は off、info、warning、error です。pythia lint --json で、すべての組み込みルール ID を確認できます。新しいルールも命名パターンと同じように測定します。既存のオブジェクトをいくつかリンティングし（pythia src の出力をファイルに保存）、コードベース全体で発動するルールは新しいコードにのみ適用されるルールなので、その旨を明記します。

チームですでに稼働している古い基盤から規約を取り入れる

接続先をそのスキーマに設定し、そこで手順1と2を実行します。何千ものオブジェクトを持つ基盤システムは、既存のチーム慣習を示す最も信頼できる情報源であり、誰かの記憶よりもはるかに確実です。次に、新しいプロジェクトに接続先を切り替えて --check を実行します。カバレッジによって、新しいスキーマが基盤のスタイルをどの程度実際に引き継いでいるかがわかります。

危険信号 — こんな考えが浮かんだら、作業を止めてください

考え	実際のところ
「ドキュメントだけを見てパターンを書こう」	ドキュメントには意図が記され、スキーマには実際に起きたことが記録されています。まずスキャンしてください。
「カバレッジが80%あれば十分だ」	見落としがあると、適用のたびに警告が出ます。パターンを修正するか、例外を記録してください。
「オブジェクト名をすべて読んで把握しよう」	--scan を使えば、コンテキストを消費せずに確認できます。
「スキーマと食い違っているから、ドキュメントが間違っている」	新しいコードにのみ適用されるルールかもしれません。確認してください。
「1行にルールを1つ書けば十分だ」	コストが書かれていないルールは、無視されてしまいます。

このスキルを使わない場合

• 既存のスタイルに沿って1つのオブジェクトを書く場合 → pythia-write。これらのファイルを読み込み、 詳細の確認には similar を使います。
• 手順やゲートを含むワークフローを記録する場合 → pythia-skill-author。 命名とスタイルはここで扱い、手順はスキルに記述します。