pythia-comment について
pythia-commentは、pythiaでSQLファイルを編集する開発者向けのコメント規約です。日付・作者・変更内容をASCIIの1行で記し、説明はドキュメントやテストなど別の場所に置く方針です。
主な機能
- 01日付・作者・変更内容を1行で記載
- 02SQLとPL/SQLのコメントが対象
- 03ASCII文字を必須化
- 04説明を文書・テスト・コミットへ移動
活用シーン
- 01SQLの変更に短いコメントを追加
- 02保存コメントの文字化けを回避
- 03設計理由を仕様書やコミットに記録
インストール
コマンドをコピーしてターミナルで実行します。
npx skills add https:/インストール後、Claude Code で/pythia-commentを入力して読み込まれたか確認します。
詳細
コメント — 1行で、または別の場所に
最初に宣言：「pythia-comment を使用します — 1行、日付 - 作成者 - 変更内容。」
**フェーズ：**実行 — ファイルに書き込む間、pythia apply がファイルを確認する前に適用されます
コメントは、コンパイラーによるチェックもテストによる確認も行われない変更の唯一の部分であり、 そのため、ここが最も劣化しやすい箇所です。1行なら次の書き換え後も残ります。段落は、次の読者が作業を始める前に反証しなければならない主張になってしまいます。
形式
-- 11/09/2026 - jdoe - source flag reads the mapping table, not the join
date - author - what changed の形式で、日付は DD/MM/YYYY とします。作成者には
開発者のハンドル名を使い、エージェントの名前は使いません。これを決めたのはエージェントではなく、
ツール名を記録した blame の履歴を追っても行き止まりになるためです。
PL/SQL と SQL では -- を使います。このスキルが扱うのはここまでです。pythia が適用する内容です。
ASCII のみを使用してください。 .sql ファイルを扱う一連の処理の一部は、今も ANSI として読み取ります。 その箇所にダイアクリティカルマークがあると、データベースに永続的に残るものが文字化けしてしまいます。 このため、ダイアクリティカルマークを使わないベトナム語表記は、まさにこの理由から定着したスタイルであり、 十分に適切なものです。
1行で
2行目が必要なら、そのコメントは入れる場所が違います。次の場所に移してください。
| 書こうとしていた内容 | 置き場所 |
|---|---|
| この形式にした理由と、そうしないと何が壊れるか | .sql 成果物のヘッダーブロック |
| 後戻りさせてはならないルール | メッセージ付きのアサーションとして、テストまたは検証ツールに記述 |
| 決定内容と、採用しなかった選択肢 | 仕様書またはチケット |
| 変更内容とその理由を、履歴を読む人に伝える内容 | コミットメッセージ |
| ステートメントの動作 | どこにも書きません。ステートメントを見ればすでに分かります |
コードから読み取れないことだけをコメントにします。落とし穴、決定事項、理由です。
してはいけないこと
- 1つのステートメントの上に、複数行の説明ブロックを書くこと。
- バナーや罫線、
-- ==== section ==== - 箇条書き、引用したエラーコード、インラインでの改訂履歴の調査。
- ドキュメント代わりにコメントアウトしたコードを残すこと。削除してください。ジャーナルと VCS の両方が記録しており、どちらも現行のコードについて偽ることはありません。
- 変更しないコードのコメントに手を入れること。それは別の差分であり、自分の変更を埋もれさせます。
完了する前に
追加したコメント行を数えてください。ステートメントあたり1行を超えるなら、削減ではなく書き換えです。
次に、コメントが実際にデータベースに反映されたことを確認してください。コメントは、2人目の書き手が気づかずに 削除しやすい種類の行です。確認には手間がかかりません。
select count(*) from all_source
where owner = :owner and name = :name and text like :marker
プレビューに表示される pythia の外部で変更されました という警告も、この確認のもう半分です。pythia が最後に書き込んでからオブジェクトが変更されていると、この警告が表示されます。