implement-backlog

サブエージェント(役割ごとの小さなAI)を難しさに応じて使い分けながら、実装を進めるスキルの説明

このスキルは、全体の中でもいちばん複雑です。ここではサブエージェント(Claude Codeが作業を分担させる、役割ごとの小さなAI)を使います。さらに、作業の難しさに応じて使うAIモデル(haiku/sonnet/opus)を切り分ける、モデル階層化という工夫が特徴のスキルです。

コマンドと主なオプション

/architect:implement-backlog [item] [--epic=<id>] [--build-context] [--review-epic[=<id>]] [--out=<path>] [--confirm-versions|--no-confirm-versions] [--refresh-versions] [--dry-run] [--auto] [--lang=en|ja]

オプション	意味
`item`	実装対象。`I1.2.3`・`#<iid>`・URLで指定する。省略時は`status::doing`のアイテムを拾い、確認を求める
`--epic`	対象Epicを絞り込む
`--build-context`	shared-contextパックを作り直す
`--review-epic[=<id>]`	Epic全体を見直すロールアップレビューを実行する
`--out`	コードの書き出し先(`source_root`)を明示する
`--confirm-versions` / `--no-confirm-versions`	依存ライブラリのバージョンをユーザーに確認するかどうか
`--refresh-versions`	記録済みのバージョン判断(`work/version-decisions.json`)を捨てて再調査する
`--dry-run`	コードを書かず、何を実装するかだけ報告する
`--auto`	途中の確認を省略する
`--lang`	コメントやレポートの出力言語

処理の流れ

Step 1(shared-contextパック構築)だけは初回のみ実行され、Step 2以降はIssueがなくなるまでループします。ノードの色は担当するモデルを示します(色の意味は下の「モデル割り当てのルール」を参照)。色が付いていないノードは、サブエージェントに任せず、このスキル自体(sonnet)が処理します。

Step 0: manifestとプラットフォームの解決

backlog-manifest.jsonというファイルを読み込みます。そして、Issueを管理する場所がGitLabかGitHubか、どちらのプラットフォームを使うかを決めます。

Step 1: shared-contextパックの構築(初回のみ)

最初の1回だけ行う作業です。sonnetのサブエージェントを複数同時に動かして、Shared-Contextパック(後の作業で共通して使う、あらかじめまとめておく情報)を作ります。

Step 2: Issue選択(ユーザーに確認)

次に取りかかるIssueを選びます。すでに作業中のもの(status::doing)があれば、それを優先します。なければ、まだ着手していないもの(status::todo)から確認します。着手する前に、選んだIssueでよいかユーザーに確認します。

Step 3: コンシステンシーダイジェスト収集

haikuのサブエージェントを使って、コードを読むだけの調査を行います。この調査結果を「コンシステンシーダイジェスト」と呼び、実装の前に必要な情報をまとめたものです。ファイルの書き換えは行いません。

Step 4: ブランチ作成 + ミニプラン策定

feature/<issue-id>-<slug>という名前で、作業用のブランチ(コードの履歴を枝分かれさせたもの)を作ります。そのうえで、opusのサブエージェントが、実装の小さな計画(ミニプラン)を立てます。

Step 5: 実装

sonnetサブエージェントが、意味のあるまとまり(コヒーレントな単位)ごとに、実際のコードを複数同時に実装していきます。

Step 5b: ドキュメント生成

/architect:generate-docsを実行して、今回の変更に合わせてREADMEやdocs/を更新します。更新分はコードと同じブランチにコミットされるので、同じPR/MRでまとめてレビューされます。ドキュメントに書かれた内容とコードのずれ(ドリフト)が見つかった場合は、その場で書き換えずにIssueへfindingとして追記します。

Step 5c: 品質ゲート(8段階)

/architect:verify-implementation --gateを実行します。ビルド、ユニット/契約/統合テスト、SAST(ソースコードを静的に解析して脆弱性を探す検査)、依存ライブラリの脆弱性スキャン、APIセキュリティレビュー、設計との一致確認を、8段階で順に通します。

各段階の合否は「コマンドが実際に走って成功したか」で決まります。「たぶん大丈夫」は合格になりません。実行しなかった段階も、理由(not-applicable / not-configured / skipped-by-user)つきで必ず記録されます。**1つでもFAILがあると、Step 6には進みません。**ブロッカーはStep 5の実装担当に差し戻され、ゲートを再実行します。人間がレビューを頼まれるのは、このゲートを通過したコードだけです。

Step 6: Epic整合性チェック

opusサブエージェントが、今回の実装がEpic全体の目的とずれていないかを判定します。この結果は、--review-epicというコマンドで複数のIssueをまとめて確認するとき(ロールアップ)に使われます。

Step 7: 進捗記録

haikuサブエージェントが、これまでの進み具合を伝えるコメントの下書きを作ります。

Step 8: 次のアイテムへ

Step 2(Issue選択)に戻り、次のIssueに取りかかります。

モデル割り当てのルール

「できる中でいちばん安いモデルを使う」という方針です。上の図の色は、この表のモデルに対応しています。

作業	モデル	図の色	理由
コンテキスト収集(Explore)、進捗コメントの下書き作成	haiku	青	ファイルを読んで要約するだけの、単純な作業だから
shared-contextパック生成、コード実装、ドキュメント生成	sonnet	緑	決まった構造に沿って文書やコードを組み立てる作業だから
ミニプラン策定、Epic整合性判定、Epicロールアップ	opus	黄	Epic全体の目的や決まりごとと合っているか、深く判断する必要があるから

ブランチ名の共有契約

feature/<issue-id>-<slug>という名前のルールは、implement-backlogが最初にブランチを作るときに使います。そのあとreview-issueとmerge-issueという別のスキルが、同じ名前のブランチを見つけてレビューやマージを行います。つまりこの命名ルールは、スキル同士が暗黙のうちに守っている共通の決まりごとです。

Output Locationの検証

コードを書き出す場所(source_root)が、Gitの管理対象外になっていないかを、書き込む前に必ず確認します。

そのために使うのがgit check-ignore -q <path>というコマンドです。これは、指定したパスが.gitignoreの対象 (Gitが追跡しないファイル・フォルダ)になっていないかを調べるコマンドです。コマンドの実行結果(終了コード、 exit code)が1であれば、「管理対象外にはなっていない」、つまり安全に書き込めるという意味です。

generated/というディレクトリ(フォルダ)は、自動生成される出力専用の場所で、多くのプロジェクトで .gitignoreの対象になっています。ここには書き込みません。

git check-ignore -q backend
echo "check-ignore exit: $?"   # 1なら、Gitの管理対象外になっていない=書き込んでも安全

依存バージョンの決定

ライブラリのバージョン番号を、AIが記憶(学習した知識)から思い込みで書いてしまうと、実際には存在しないバージョンや、すでに古くなったバージョンを指定してしまう事故が起こります。これを防ぐために、 @rules/dependency-versions.mdというルールファイルには「バージョン番号を記憶から書くな、必ずレジストリ (パッケージの配布元)で調べよ」と定められています。

実際の例として、Maven Central(Javaのライブラリを配布しているサイト)からmaven-metadata.xmlというファイルをcurlコマンドで直接取得し、最新のバージョンを確認した例があります。このとき、Spring Bootの 4.1.0は「まだパッチ(細かい修正版)が出ていない、リリースされたばかりのマイナーバージョン」だったため、あえてより枯れた(実績があり安定している)4.0.7を選びました。この判断の理由はwork/version-decisions.json というファイルに記録されています。