体系的なエージェント — 規律あるコーディングプラクティス
使用すべきタイミング
すべてのコーディングタスク、変更、デバッグセッション、実装作業。このスキルは、コード変更に取り組む方法のベースラインオペレーティングシステムであり、オプションのアドオンではありません。
すべてのコード関連タスクで自動的に呼び出されます。ユーザーがコードの変更、追加、修正、構築を依頼した場合は、このスキルに従ってください。
コアルール
1. プロジェクトに関する事実を決して推測しない
ファイルに触れる前に、実際に何があるかを知っている必要があります。ファイルを読んでください。現在の状態を確認してください。そこに「あるべき」ものの記憶に頼らないでください。
具体的なアクション:
- 変更しようとしているファイルを、周辺コンテキストを含めて
read_fileする - 関連するコード、インポート、関数呼び出し元、参照を
search_filesする - 変更をテストする前にサーバーが実行中でエンドポイントが応答することを確認する
- 設定ファイルに実際に想定している内容が含まれていることを確認する
2. 何かを変更する前に関連ファイルを調査する
盲目的にパッチを当てないでください。編集する予定のファイルごとに:
- ファイル全体（または十分なコンテキストを含む関連セクション）を読む
- 現在の構造、インポート、依存関係、パターンを理解する
- 何を変更する必要があるか、その理由を特定する
- その後にのみパッチまたは編集を記述する
パッチを適用するとき: old_string に十分な周辺コンテキストを含めて、マッチを一意にしてください。複数の場所にマッチするパッチは、間違った場所に適用されます。
大きなファイルを読むとき: offset/limit を使用して段階的に読み取ってください。1つの関数だけが必要な場合に1600行のファイルを1回の呼び出しでロードしようとしないでください。ただし、変更する関数は、そのシグネチャとすべての呼び出しサイトを含めて完全に読んでください。
3. 実行前に簡潔な計画を立てる
重要でないコーディングタスクの前に、以下の質問に答える簡単な計画（3〜7個の箇条書き）を書いてください:
- どのファイルを変更する必要があるか
- 各変更が何をするか（変更ごとに1行）
- 変更をどの順序で行うべきか
- 成功を確認するための検証手順は何か
例:
計画:
1. app.py の762〜770行目を読む — _get_hermes_response のシグネチャを確認
2. image_url: str = None パラメータをシグネチャに追加
3. 関数内のすべての5つの _call_api 呼び出しに image_url=image_url を追加
4. chat() から _get_hermes_response に image_url を渡す
5. サーバーを再起動し、curl画像ペイロードでテストする
計画を述べるまでコーディングを開始しないでください。 計画が間違っていれば、コードも間違っています。
4. ツールを使用して主張を検証し、推測しない
コードベースに関するすべての主張は、ツールの出力に裏付けられている必要があり、記憶に基づいてはいけません。
| 主張 | 検証方法 |
|---|---|
| 「ファイルXに関数Yがある」 | grep -n またはファイルを read_file する |
| 「サーバーが実行中である」 | curl でヘルスエンドポイントにアクセスする |
| 「変更が機能する」 | 実際のテストを実行し、推測しない |
| 「APIキーが設定されている」 | storage/apis.json を読む |
| 「CSSがロードされている」 | curl で静的ファイルにアクセスし、HTTPステータスを確認する |
| 「パッチが正しく適用された」 | 新しいテキストを grep するか、領域を read_file する |
「機能するはずです」という応答を、実際に機能することを確認せずに書かないでください。
5. 重要な変更のたびに、結果をテストまたは検査する
コード変更後:
- 構文チェック:
python3 -c "import py_compile; py_compile.compile('app.py', doraise=True)"— 再起動前に合格している必要があります - サーバーを再起動する (変更が app.py にある場合)
- 変更された動作をテストする:
- API変更の場合: 代表的なペイロードでエンドポイントに
curlする - フロントエンド変更の場合: 静的ファイルが提供されていることを確認する（HTTP 200）
- 設定変更の場合: 設定ファイルを読んで確認する
- API変更の場合: 代表的なペイロードでエンドポイントに
- 実際の出力を確認する — 期待したものではなく、ツールが返したものを確認する
テスト結果を確認するまで変更は完了していません。 「動くと思う」は検証ではありません。
6. 何かが失敗した場合、別のアプローチを試みる前に実際のエラーを診断する
テストが失敗した場合やパッチが適用されない場合:
- 実際のエラーメッセージを読む — そのままコピーする。要約しない。
- 根本原因を特定する — 具体的に何が失敗し、なぜ失敗したか
- 修正について仮説を立てる
- ツールを使用して仮説をテストする — 別のパッチを適用するだけではいけない
- 修正が機能しない場合、エラーを読み直す — 変更されているか、誤読している可能性がある
避けるべきアンチパターン:
- どれかが機能したか確認せずに、3つの異なるパッチを連続して適用する
- エラーテキストを読まずにエラーの種類に基づいて修正を推測する
- エラーが1つの特定の場所にある場合に無関係なコードを変更する
- サーバーの起動を妨げる構文エラーを修正せずにサーバーを再起動する
7. 結果が検証されるまでタスクが完了したと言わない
タスクが完了するのは、次の場合のみ:
- コード変更が記述され、構文チェックが行われた ✓
- 新しいコードでサーバーが実行中である ✓
- 変更された動作が期待どおりの結果を生成する（ツール出力で確認） ✓
- それを証明する特定のテスト/コマンド/出力を指し示せる ✓
パッチが正常に適用されたことに基づいて「完了」と宣言しないでください。 パッチは間違った場所に適用されたり、構文エラーが発生したり、実際に問題を修正しなかったりする可能性があります。パッチの適用は検証のステップ1であり、終わりではありません。
手順
コード変更の場合:
- 読む — 変更するファイルを調査する。現在の状態を知る。
- 計画する — 3〜7個の箇条書きを書く: 何を変更するか、どの順序で、どのように検証するか。
- 変更する — 編集を行う。複数ファイルの作業では、アトミックな変更を1つずつ行う。
- 構文チェック —
py_compileまたは同等のもの。先に進む前にエラーを修正する。 - 再起動する — 実行中のサーバーが新しいコードを必要とする場合。
- テストする — curl、実行、または検査。実際の動作が意図と一致することを確認する。
- 報告する — 何が変更されたか、テストで何が示されたか、検証されたかどうかを述べる。
デバッグの場合:
- 再現する — 実際のエラー出力を取得する。そのままコピーする。
- 特定する — コード内でエラーが発生する場所を見つける。
grep、read_file、スタックトレース。 - 理解する — 失敗しているコードを完全に読む。何をするか推測しない — 読む。
- 仮説を立てる — この特定のエラーを修正する具体的な変更は何か？
- 修正する — 根本原因に対処する最小限の変更を行う。
- 検証する — 失敗したテストを再実行する。エラーがなくなったことと、他に何も壊れていないことを確認する。
- まだ失敗している場合 — ステップ1に戻る。エラーが変わっている可能性がある。読み直す。
複数ステップのタスクの場合:
- 一度に1つのステップを実行する。次のステップに進む前に各ステップを検証する。
- ステップ3がステップ2の正しさに依存する場合、最初にステップ2を検証する。
- 未検証の変更をバッチ処理しない — ステップ2が間違っている場合、ステップ3の「修正」も間違っている。
落とし穴
- 行動せずに同じ行を繰り返し読む。 関数を3回読んでも編集していない場合、行き詰まっている。変更を行うか、何が邪魔をしているかを述べるか。
- ファイルの内容を推測する。 常にファイルを読む。複数のパッチを適用した後は「そこにあった」という記憶は信頼できない。
- 構文チェックをスキップする。 パッチは正常に適用されても構文を壊す可能性がある。常に確認する。
- 再起動せずにテストする。 app.py が変更された場合、実行中のサーバーには古いコードがある。テストする前に再起動する。
- パッチ成功で完了を宣言する。 「パッチ適用済み」≠「タスク完了」。動作を検証する。
- エラーメッセージを読まない。 エラーテキストは何が失敗したかを教えてくれる。それを読む。エラーの種類だけで推測しない。
- 過剰にパッチを適用する。 特定の問題を修正する最小限の変更を適用する。1行が間違っているときに関数全体を書き換えない。
検証チェックリスト
コーディングタスクの完了を報告する前に、各項目を確認する:
- 変更前にファイルを読んだ（現在の状態を知っている）
- 計画を書いた（何を変更するか、どの順序で）
- 構文チェックが合格した（
py_compileまたは同等のもの） - app.py が変更された場合はサーバーを再起動した
- テストを実行した（curl、実行、または検査） — 実際の出力を見た
- 出力が期待される動作と一致する
- 新しいエラーが導入されていない
このスキルと他のスキルとの相互作用
- これはベースラインスキルです — 他のどのスキルがアクティブであっても、すべてのコーディング作業に適用されます
test-driven-developmentがアクティブな場合、TDDがテスト方法になります。このスキルは全体的な規律を管理しますsystematic-debuggingがアクティブな場合、デバッグには独自の詳細な手順があります。このスキルのルール6は引き続き適用されますspikeがアクティブな場合（使い捨ての実験）、「変更前の調査」と「変更後の検証」ルールは引き続き適用されます — スパイクは雑であっても不注意であってはなりませんhuman-first-uiまたはwebmxerzがデザイン作業でアクティブな場合、このスキルはデザインを実装するコード変更を管理します。デザインスキルは何を構築するかを指示し、このスキルはどのように安全に構築するかを管理します- スキルは
skill_view(name)を介してオンデマンドでロードされます — 継続的にアクティブなバックグラウンドプロセスではありません。スキルはロードされたセッションターン中にのみプレイ中になります。デザイン支援スキル（webmxerz、human-first-ui）は特定のUIタスクのために参照されます。このスキルはデザインを実装するコード作業のベースラインのままです。