self-improving-agent

自己改善エージェント

このスキルを使うタイミング：

• 重要なタスクの完了後（タスク後の振り返り）
• 複数手順のワークフローを繰り返していることに気づいたとき
• 人間から行動を修正され、その修正を記録しておく必要があるとき
• AGENTS.md のコードベースマップが古くなっているとき
• 作業セッションの終了時

---

ステップ 1：改善が必要な点を診断する

作業を完了した後、次の質問を自分に問いかけてください。

1. 迷走しましたか？ コードベースマップに記載されているはずのファイルを探すのに時間を費やしましたか？

   • → AGENTS.md の コードベースマップ を更新します

2. 修正されましたか？ 人間から、別の方法で行うよう指示されましたか？

   • → AGENTS.md の ローカル規約、ガードレール、または パターンと注意点 に修正内容を追加します

3. ワークフローを繰り返しましたか？ 以前も行った（または今後も行う可能性が高い）複数手順の作業を実施しましたか？

   • → 新しい スキル を作成します（下記のステップ 3 を参照）

4. 意外なことがありましたか？ 注意点、非推奨の API、または自明でない依存関係を見つけましたか？

   • → AGENTS.md の パターンと注意点 に追加します

5. AGENTS.md は古くなっていますか？ 規約、エントリーポイント、または慣例が、実際のコードベースと合わなくなっていますか？

   • → 古くなったセクションを今すぐ更新します

いずれにも当てはまらない場合、対応は不要です。必要もないのに成果物を作成しないでください。

---

ステップ 2：AGENTS.md を更新する

AGENTS.md を更新するときは、次のルールに従ってください。

コードベースマップの更新

1. AGENTS.md の現在のマップを読みます。
2. find または ls（再帰的にツリー全体を表示する方法ではなく）を使って、実際の最上位構造を確認します。
3. 変更があった箇所だけを更新します。マップ全体を書き直さないでください。
4. エントリーポイント、ディレクトリの役割、設定ファイル、テストの場所を中心に確認します。

規約やガードレールの追加

1. ルールは 短く、命令形の文 で書きます。できれば 1 行にまとめます。
2. 適切なセクションに記載します。
   • ローカル規約 → このリポジトリでのコードのビルド、テスト、実行、スタイル
   • ガードレール → エージェントが絶対にしてはならないこと
   • パターンと注意点 → コードベースに関する自明でない発見
3. 修正内容が既存の項目と矛盾する場合は、重複して追加するのではなく、既存の項目を更新します。

品質チェック

• 項目は簡潔にします。エージェントは毎回のセッションでこれを読むため、簡潔さが積み重なります。
• 実際の項目が追加されたら、プレースホルダーや例の項目（イタリック体）を削除します。
• 一般的な助言は追加しないでください。すべての項目は このリポジトリ固有 にします。

---

ステップ 3：新しいスキルを作成する

繰り返し実行でき、記録する価値のあるワークフローを特定した場合は、この手順を使います。

判断：これはスキルか、AGENTS.md の項目か？

Is it a multi-step procedure with a clear output?
  → YES → Skill
  → NO  → AGENTS.md entry

Is it specific to HOW this repo works (norms, navigation)?
  → YES → AGENTS.md entry
  → NO  → Skill

Am I unsure?
  → Start as an AGENTS.md entry. Promote to skill if it grows.

スキルの作成

1. 名前を決めます。 作業内容を表す動詞と名詞の組み合わせにします。例：debug-ci、draft-release-notes、run-migration など。

2. フォルダーとファイルを作成します。

   skills/<skill-name>/SKILL.md
   

3. 次の構成で SKILL.md を記述します。

   ---
   name: <skill-name>
   description: <one-line description of what job this skill does>
   ---
   
   # <Skill Name>
   
   > **When to use:** <clear trigger condition>
   
   ## Steps
   
   1. <Step 1 — be specific and imperative>
   2. <Step 2>
   3. ...
   
   ## Output Contract
   
   <What "done" looks like. Be specific about format, location, and quality.>
   

4. 良いスキルを作るための主な原則：

   • ツールではなく、達成すべき作業 を中心にします（「grep を使う」ではなく「CI の失敗をデバッグする」）。
   • 実行のきっかけ を明確にします。エージェントはどのようなときにこのスキルを使うべきですか？
   • 出力の条件 を定義します。「完了」とはどのような状態ですか？
   • 役立つ場合は、良い出力例をアセットとして含めます（skills/<name>/examples/ に配置します）。
   • 手順は 命令形で具体的に 書き、曖昧な指示は避けます。

5. AGENTS.md のスキル一覧に新しいスキルを追加します。

   | [<skill-name>](skills/<skill-name>/SKILL.md) | <purpose> | <trigger> |
   

スキルへのスクリプトやアセットの追加

決定的な実行（LLM の判断だけに頼らない実行）が必要なスキルには、スクリプトを追加します。

skills/<skill-name>/
├── SKILL.md          # The playbook (always required)
├── scripts/          # Helper scripts for deterministic steps
│   └── validate.sh
└── examples/         # Reference outputs showing "good" quality
    └── example-output.md

これらを SKILL.md から参照します。「scripts/validate.sh を実行して出力を検証します。」

---

ステップ 4：適用範囲を決める — リポジトリ固有、グローバル、共有

Does this skill only matter for THIS repo?
  → Keep it in skills/ within this repo (repo-local)

Have I felt this pain in another repo too?
  → Promote to ~/.agent/skills/<name>/ (machine-global)
  → Copy the skill folder there

Does my team keep repeating this workflow?
  → Promote to a shared repo or registry (shared)
  → Move the skill folder into the team's shared skills repo

昇格チェックリスト

スキルをリポジトリ固有からグローバルに昇格させる場合：

1. SKILL.md からリポジトリ固有のパスや参照を削除します。
2. どのプロジェクトでも使えるよう、手順を汎用化します。
3. 元のリポジトリのコンテキストなしで動作することを確認します。
4. リポジトリ固有のカスタマイズがある場合は、リポジトリ固有のバージョンも残します。

---

ステップ 5：改善を検証する

変更（AGENTS.md の更新または新しいスキルの追加）を行ったら、次のことを確認します。

1. 更新したファイルを読み直します。 内容は明確ですか？ 新しいセッションのエージェントにとって役立ちますか？
2. 矛盾がないか確認します。 新しい項目は既存の内容と矛盾していませんか？
3. 肥大化していないか確認します。 ファイルが長くなりすぎていませんか？ AGENTS.md が約 200 行を超える場合は、次の対応を検討してください。
   • 古くなった注意点をアーカイブする
   • 詳細な手順をスキルに移す
   • 冗長な項目を要約する
4. 明確なメッセージを付けて変更をコミットします。

   docs: update AGENTS.md with <what you learned>
   

   または

   feat: add <skill-name> skill for <job description>
   

---

避けるべきアンチパターン

❌ してはいけないこと	✅ 代わりにすること
一般的なアドバイスを追加する（「クリーンなコードを書く」）	リポジトリ固有のルールを追加する（「npm ではなく pnpm を使う」）
一度限りのタスク用にスキルを作成する	今後も繰り返し行うタスク用にスキルを作成する
AGENTS.md を際限なく大きくする	古い項目を整理し、手順をスキルに移す
曖昧なスキル手順を書く（「問題点を見つける」）	具体的な手順を書く（「npm test を実行し、最初に失敗したアサーションを読む」）
ツールを中心にスキルを作成する	実行する作業を中心にスキルを作成する
最初から共有／グローバルスキルを作成する	リポジトリ内で始め、同じ課題が繰り返されたら共有する

---

クイックリファレンス：複利のループ

Work on task
    ↓
Complete task
    ↓
Reflect: Did I wander? Get corrected? Repeat a workflow? Discover a gotcha?
    ↓
    ├── Navigation miss     → Update Codebase Map
    ├── Behavior correction → Add to Local Norms / Guardrails
    ├── Repeated workflow   → Create a Skill
    ├── Surprise discovery  → Add to Patterns & Gotchas
    └── Nothing notable     → Move on
    ↓
Next task starts from a better baseline

「最も価値のあるスキルは、自分の作業を見つめる習慣です。」 改善を重ねるたびに、次の改善が容易になります。これがエージェントの成長につながります。