agent-engineering

エージェントエンジニアリングの原則

信頼性が高く、質の高い成果を生み出す AI コーディングエージェントの、実践で検証された原則です。

このスキルを使う場面

• プロジェクトの AGENTS.md／CLAUDE.md／CURSOR.md ファイルを作成またはレビューするとき
• 新しい AI コーディングエージェントまたはサブエージェントを設定するとき
• エージェントが同じミスを繰り返す原因を調べるとき
• エージェントの出力品質をレビューし、体系的な問題を特定するとき
• 複雑なコードベースにエージェントをオンボーディングするとき

1. デフォルトで計画モードを使う

• 重要なタスク（3 ステップ以上、またはアーキテクチャ上の判断を伴うもの）では、必ず計画モードに入ります
• 何か問題が起きたら、作業を続けずにすぐに止めて計画を立て直します
• 計画モードは、構築だけでなく検証の手順にも使います
• 曖昧さを減らすため、事前に詳細な仕様を書きます

省略できる場合： 解決策が明白な、単純な単一ファイルの編集。

計画の例（tasks/todo.md）：

## Task: Migrate auth to JWT

### Plan
- [ ] Audit current session-based auth flow
- [ ] Design JWT payload schema (user_id, roles, expiry)
- [ ] Implement token generation in auth service
- [ ] Update middleware to validate JWT
- [ ] Write tests for edge cases (expired, invalid, revoked)
- [ ] Update docs

### Done
- [x] Audit complete — 4 routes need updating

2. サブエージェント戦略

• メインのコンテキストウィンドウをきれいに保つため、積極的にサブエージェントを使います
• 調査、探索、並行分析はサブエージェントに任せます
• 複雑な問題には、サブエージェントを使って計算リソースをより多く投入します
• 集中して実行できるよう、サブエージェントにはタスクを 1 つだけ割り当てます

重要なポイント： コンテキストウィンドウの汚染は、エージェントの品質低下の最大の原因です。サブエージェントは低コストなので、活用しましょう。

サブエージェントを使う場合と、インラインで作業する場合：

サブエージェントを使う	インラインで作業する
調査タスク（10 ファイル超）	単純な 1 ファイルの編集
独立した並行作業	簡単な設定変更
時間のかかるコンパイルやテストの実行	出力が明確な単一のコマンド
切り分けた実験（リスクのある変更）	ささいなリファクタリング

3. 自己改善ループ

ユーザーから修正を受けたら、必ず次の手順を行います。

1. tasks/lessons.md（または同等のファイル）に、パターンを記録します
2. 同じミスを防ぐため、自分向けのルールを書きます
3. ミスの発生率が下がるまで、これらの教訓を徹底的に反復します
4. セッション開始時に、関連するプロジェクトの教訓を確認します

教訓の形式

## Lesson: [Short title]
- **Trigger:** What went wrong
- **Rule:** What to do instead
- **Added:** [date]

教訓の例：

## Lesson: Don't mutate shared config objects
- **Trigger:** Modified `config.defaults` directly, breaking other callers
- **Rule:** Always deep-clone config before modifying; treat config objects as read-only
- **Added:** 2026-03-15

これは、エージェントのパターンの中でも最も活用されていません。 フィードバックの仕組みがないため、多くのエージェントは同じミスを繰り返します。教訓を記録するファイルがあれば、このループを閉じることができます。

4. 完了前に検証する

• 動作することを確認せずに、タスクを完了扱いにしてはいけません
• 関連する場合は、メインブランチと変更後の動作を比較します
• 「スタッフエンジニアならこれを承認するだろうか？」と自問します
• テストを実行し、ログを確認し、正しさを実証します

アンチパターン： 動作する証拠がないまま「変更しました」と報告すること。

完了扱いにする前の検証チェックリスト：

• テストが成功する（npm test／pytest／go test ./...）
• 新たな lint エラーがない
• 変更したコードパスを手動でスモークテストする
• 意図しない変更がないか差分をレビューする
• エッジケース（空の入力、エラー処理、並行アクセス）を検討する

5. 洗練さを求める（バランスを保つ）

• 重要な変更では、いったん立ち止まり「もっと洗練された方法はないか？」と考えます
• 修正が場当たり的に感じられたら、「今わかっていることをすべて踏まえて、洗練された解決策を実装する」と考えます
• 単純で明白な修正では省略します。過剰に設計してはいけません
• 提示する前に、自分の作業を批判的に見直します

バランス： 洗練さは、保守されるコードで重要です。使い捨てのスクリプトなら、そのまま仕上げましょう。

洗練されている兆候： コードが文章のように読めます。新しいエンジニアでも説明なしに理解できます。抽象化の境界が明確です。追加するものも、削除するものもありません。

過剰設計の兆候： 20 行の問題に対して抽象化レイヤーが 3 つある。一度きりの用途に汎用フレームワークを作る。「後で必要になるかもしれない」という理由で実装する。

6. 自律的なバグ修正

• バグ報告を受けたら、そのまま修正します。手取り足取り教えてもらおうとしないでください
• ログ、エラー、失敗しているテストを示し、解決します
• ユーザーがコンテキストを切り替える必要はありません
• 指示がなくても、失敗している CI テストを修正します

目安： エラーを確認でき、コードベースを理解しているなら、修正してください。本当に行き詰まった場合にのみ質問します。

行き詰まった状態とは：

• 修正にプロダクトや UX に関する判断が必要な場合（技術的な判断ではない場合）
• 持っていないアクセス権や認証情報が必要な場合
• 妥当な修正方法が 2 つあり、トレードオフに大きな違いがあるため、オーナーが選ぶべき場合

7. タスク管理サイクル

重要なタスクでは、次の 6 ステップのサイクルに従います。

1. まず計画する： チェック可能な項目を tasks/todo.md に書きます
2. 計画を確認する： 実装を始める前に確認を求めます
3. 進捗を記録する： 作業を進めながら項目を完了にします
4. 変更内容を説明する： 各ステップで概要を説明します
5. 結果を記録する： tasks/todo.md にレビューのセクションを追加します
6. 教訓を記録する： 修正後に tasks/lessons.md を更新します

基本原則

• シンプルさを最優先する： 変更はできる限りシンプルにし、コードへの影響を最小限に抑えます
• 手を抜かない： 根本原因を突き止めます。一時しのぎの修正はしません。シニア開発者としての基準を守ります
• 動作を証明する： テスト、ログ、証拠を示します。「動くはず」では不十分です
• 失敗から学ぶ： 修正のたびに、教訓を恒久的なルールにします
• コンテキストを大切にする： メインのコンテキストを整理し、積極的に作業を委任します
• 議論よりリリースを優先する： 行動を優先します。議論するのではなく、修正します

よくある失敗パターン（アンチパターン）

終わりのないループ

エージェントが少しだけ方法を変えながら、同じ失敗するアプローチを何度も試します。対策： 作業を止め、エラーを読み直し、教訓ファイルを参照して、根本的に異なる方法を試します。

コンテキストのずれ

ツールを 20 回以上呼び出した後、エージェントが当初の目標を見失い、隣接する問題を解決し始めます。対策： 主要なマイルストーンごとに、元のタスクを読み直します。

時期尚早な確信

エージェントが「コードは正しそうだ」という理由だけで、実行せずにタスクを完了扱いにします。対策： 必ずテストやコマンドを実行し、思い込みに頼らないでください。

スコープの拡大

バグを修正するついでに、エージェントが無関係なコードまでリファクタリングします。対策： 1 つの変更につき 1 つのコミットにします。リファクタリングは別の PR に分けます。

気づかれない失敗

コマンドは終了コード 0 で終了しますが、実際には何も変わっていません（例：ドライランモードが有効なままになっている）。対策： 変更が反映されたことを確認します（ログ、差分、設定の再読み込みを確認します）。

これらの原則の適用

AGENTS.md / CLAUDE.md ファイルの場合

関連する原則を、プロジェクトのエージェント設定に直接追加します。

## Engineering Standards

### Before Starting
- [ ] Read tasks/lessons.md for this project
- [ ] Plan non-trivial work in tasks/todo.md
- [ ] Verify plan before implementing

### While Working
- [ ] One task per subagent
- [ ] Verify each step works before moving on
- [ ] Track progress in todo.md

### Before Marking Done
- [ ] Run tests / check logs
- [ ] "Would a staff engineer approve this?"
- [ ] Update lessons.md if any corrections were made

CI／レビューへの統合

これらの原則は、PR レビューの自動化に適しています。

• 検証（#4） → PR の説明でテストの証拠を必須にします
• 洗練さ（#5） → コードレビューチェックリストの項目にします
• 教訓（#3） → マージ後の振り返りメモにします

新しいプロジェクトの立ち上げ

tasks/ ディレクトリがない新しいコードベースの場合：

mkdir tasks
echo "# Todo\n\n(empty)" > tasks/todo.md
echo "# Lessons\n\n(empty)" > tasks/lessons.md

次に、これらのファイルがエージェント専用なら両方を .gitignore に追加し、チームで共有するなら追跡対象にします。

参考資料

コミュニティで共有されているエージェントエンジニアリングのパターンに着想を得ています（2026 年 3 月）。