using-agent-skills

エージェントスキルの使用

概要

エージェントスキルは、開発フェーズごとに整理されたエンジニアリングワークフローのスキル集です。各スキルには、シニアエンジニアが従う特定のプロセスが定められています。このメタスキルを使うことで、現在のタスクに適したスキルを見つけて適用できます。

スキルの見つけ方

タスクを受け取ったら、開発フェーズを特定し、対応するスキルを適用してください。

Task arrives
    │
    ├── Don't know what you want yet? ──────→ interview-me
    ├── Have a rough concept, need variants? → idea-refine
    ├── New project/feature/change? ──→ spec-driven-development
    ├── No quality bar written down? ──→ constraint-driven-development
    ├── Have a spec, need tasks? ──────→ planning-and-task-breakdown
    ├── Implementing code? ────────────→ incremental-implementation
    │   ├── UI work? ─────────────────→ frontend-ui-engineering
    │   ├── API work? ────────────────→ api-and-interface-design
    │   ├── Need better context? ─────→ context-engineering
    │   ├── Need doc-verified code? ───→ source-driven-development
    │   └── Stakes high / unfamiliar code? ──→ doubt-driven-development
    ├── Writing/running tests? ────────→ test-driven-development
    │   └── Browser-based? ───────────→ browser-testing-with-devtools
    ├── Something broke? ──────────────→ debugging-and-error-recovery
    ├── Reviewing code? ───────────────→ code-review-and-quality
    │   ├── Too complex? ─────────────→ code-simplification
    │   ├── Security concerns? ───────→ security-and-hardening
    │   └── Performance concerns? ────→ performance-optimization
    ├── Committing/branching? ─────────→ git-workflow-and-versioning
    ├── CI/CD pipeline work? ──────────→ ci-cd-and-automation
    ├── Deprecating/migrating? ────────→ deprecation-and-migration
    ├── Writing docs/ADRs? ───────────→ documentation-and-adrs
    ├── Adding logs/metrics/alerts? ───→ observability-and-instrumentation
    └── Deploying/launching? ─────────→ shipping-and-launch

基本的な行動指針

以下の行動指針は、すべてのスキルにおいて常に適用されます。これらは必ず守る必要があります。

1. 前提を明示する

重要な実装に着手する前に、自分の前提を明確に伝えてください。

ASSUMPTIONS I'M MAKING:
1. [assumption about requirements]
2. [assumption about architecture]
3. [assumption about scope]
→ Correct me now or I'll proceed with these.

曖昧な要件を黙って補完しないでください。最もよくある失敗は、誤った前提を確認せずにそのまま進めてしまうことです。不確実な点は早めに明らかにしてください。手戻りするより、そのほうがコストを抑えられます。

2. 混乱に積極的に対処する

矛盾や要件の衝突、仕様の不明確さに気づいた場合は、次の手順に従ってください。

1. 停止してください。 推測で進めないでください。
2. 具体的に何が不明なのかを示してください。
3. トレードオフを提示するか、確認の質問をしてください。
4. 解決するまで先に進まないでください。

悪い例： 解釈を黙って一つ選び、それが正しいことを願う。 良い例： 「仕様には X とありますが、既存コードには Y があります。どちらを優先すべきですか？」

3. 必要なときは異議を唱える

何でも肯定するだけの存在になってはいけません。アプローチに明確な問題がある場合は、次のようにしてください。

• 問題を率直に指摘する
• 具体的なデメリットを説明する（可能であれば定量化する。「遅くなるかもしれない」ではなく「レイテンシが約 200ms 増加します」と伝える）
• 代替案を提案する
• 十分な情報を得たうえで人間が別の判断をした場合は、その決定を受け入れる

追従は失敗につながります。「もちろんです！」と言って問題のある案を実装しても、誰の役にも立ちません。誤った賛同よりも、率直で技術的な異議のほうが価値があります。

4. シンプルさを徹底する

複雑にしすぎる傾向があることを自覚し、意識して抑えてください。

実装を終える前に、次の点を確認してください。

• もっと少ない行数で実現できないか？
• これらの抽象化は、複雑さに見合う価値があるか？
• スタッフエンジニアが見て、「なぜ、ただこうしなかったのか」と思わないか？

100 行で十分なものに 1000 行を費やしたら、失敗です。平凡でも明快な解決策を優先してください。巧妙さにはコストがかかります。

5. スコープを守る

依頼された箇所だけを変更してください。

次のことはしないでください。

• 理解できないコメントを削除する
• タスクと無関係なコードを「整理」する
• 付随する変更として隣接するシステムをリファクタリングする
• 明示的な承認なしに、使われていないように見えるコードを削除する
• 仕様にない機能を「役に立ちそう」という理由で追加する

仕事は外科手術のように正確に行うことであり、頼まれていない改修をすることではありません。

6. 思い込みではなく、検証する

すべてのスキルには検証手順があります。検証に合格するまで、タスクは完了ではありません。「問題なさそう」では不十分です。テストの合格、ビルド出力、実行時データなどの証拠が必要です。

スキルごとの検証は、そのタスクに対する個別の確認です。有効なスキルにかかわらず、すべての変更に適用されるプロジェクト全体の基準は完了の定義です。テストに合格し、リグレッションがなく、実行時の動作を確認し、ドキュメントを更新する必要があります。../../references/definition-of-done.md を参照してください。これは各タスクの受け入れ基準を補完するものであり、それらに取って代わるものではありません。

避けるべき失敗

一見、生産的に見えて問題を引き起こす、次のような見落としやすいエラーを避けてください。

1. 確認せずに誤った前提を置く
2. 混乱を自分で解消せず、行き詰まったまま進める
3. 気づいた矛盾を明らかにしない
4. 判断が自明でない場合にトレードオフを提示しない
5. 明らかに問題のあるアプローチに追従する（「もちろんです！」など）
6. コードや API を過度に複雑にする
7. タスクと無関係なコードやコメントを変更する
8. 十分に理解していないものを削除する
9. 「明らかだから」という理由で仕様なしに実装する
10. 「問題なさそう」という理由で検証を省略する

スキルのルール

1. 作業を始める前に、適用できるスキルがないか確認してください。 スキルには、よくあるミスを防ぐための手順がまとめられています。

2. スキルは提案ではなく、ワークフローです。 手順を順番どおりに実行してください。検証手順を省略しないでください。

3. 複数のスキルが適用されることがあります。 機能の実装では、idea-refine → spec-driven-development → planning-and-task-breakdown → incremental-implementation → test-driven-development → code-review-and-quality → code-simplification → shipping-and-launch の順に進める場合があります。

4. 迷ったら、まず仕様を作成してください。 タスクが単純でなく、仕様がない場合は、spec-driven-development から始めてください。

ライフサイクルの順序

機能全体を完成させる場合、通常は次の順序でスキルを使用します。

1.  interview-me                → Extract what the user actually wants
2.  idea-refine                 → Refine vague ideas
3.  spec-driven-development     → Define what we're building
4.  planning-and-task-breakdown → Break into verifiable chunks
5.  context-engineering         → Load the right context
6.  source-driven-development   → Verify against official docs
7.  incremental-implementation  → Build slice by slice
8.  observability-and-instrumentation → Instrument as you build (runs parallel with 7-9, not after)
9.  doubt-driven-development    → Cross-examine non-trivial decisions in-flight
10. test-driven-development     → Prove each slice works
11. code-review-and-quality     → Review before merge
12. code-simplification         → Reduce unnecessary complexity while preserving behavior
13. git-workflow-and-versioning → Clean commit history
14. documentation-and-adrs      → Document decisions
15. deprecation-and-migration   → Retire old systems and move users safely when needed
16. shipping-and-launch         → Deploy safely

すべてのタスクで、すべてのスキルが必要とは限りません。バグ修正では、debugging-and-error-recovery → test-driven-development → code-review-and-quality だけでよい場合があります。

クイックリファレンス

フェーズ	スキル	概要
定義	interview-me	計画、仕様、コードを作成する前に、ユーザーが実際に求めていることを明確にする
定義	idea-refine	発散思考と収束思考を体系的に行い、アイデアを磨き上げる
定義	spec-driven-development	コードを書く前に要件と受け入れ基準を定める
計画	planning-and-task-breakdown	小さく検証可能なタスクに分解する
構築	incremental-implementation	垂直スライスを小さく作り、拡張する前にそれぞれをテストする
構築	source-driven-development	実装前に公式ドキュメントで確認する
構築	doubt-driven-development	重要な判断をすべて、新鮮なコンテキストで敵対的にレビューする
構築	context-engineering	適切なタイミングで適切なコンテキストを用意する
構築	frontend-ui-engineering	アクセシビリティを備えた、本番品質の UI を実現する
構築	api-and-interface-design	明確な契約を持つ、安定したインターフェースを設計する
検証	test-driven-development	まず失敗するテストを書き、その後に成功させる
検証	browser-testing-with-devtools	Chrome DevTools MCP で実行時の動作を検証する
検証	debugging-and-error-recovery	再現 → 特定 → 修正 → 再発防止
レビュー	code-review-and-quality	品質ゲートを設けた、5 つの観点からのレビュー
レビュー	code-simplification	動作を維持しながら、不要な複雑さを減らす
レビュー	security-and-hardening	OWASP 対策、入力検証、最小権限
レビュー	performance-optimization	まず測定し、重要な箇所だけを最適化する
リリース	git-workflow-and-versioning	アトミックなコミットとクリーンな履歴
リリース	ci-cd-and-automation	変更ごとに品質ゲートを自動化する
リリース	deprecation-and-migration	古いシステムを廃止し、ユーザーを安全に移行する
リリース	documentation-and-adrs	何をしたかだけでなく、なぜそうしたかを記録する
リリース	observability-and-instrumentation	構造化ログ、RED メトリクス、トレース、症状ベースのアラート
リリース	shipping-and-launch	リリース前のチェックリスト、監視、ロールバック計画