forge-implement

変更を実装する

プロジェクトの規約に従って、機能を実装するか不具合を修正します。

入力

主な入力（$ARGUMENTS）：Issue 番号／URL、プランファイルのパス、または自由形式の説明。任意で、実行時の指針として -- <additional context> を指定できます。

無人モード： --unattended を指定すると、プランの承認を省略し、確認プロンプトなしで処理を進めます。

プロセス

ステップ 1：作業内容を把握する

status-reporting に従って implementing を報告します。入力の種類を特定し、要件を抽出します。Issue トラッカーのプロバイダーを検出します（issue-operations を参照）。

• Issue — プロジェクトの Issue トラッカーを使って取得します（issue-operations を参照）。タイトル、要件、受け入れ条件、ラベル、サブ Issue、コメントを解析します。不足しているラベルがあれば追加します。Issue にサブ Issue がある場合は、それぞれを個別のタスクとして扱い、完了したものからクローズします。
• プランファイル — 目標、要件、制約、受け入れ条件を抽出します。
• 自由形式のテキスト — 対象範囲と制約を解析します。

要件が曖昧すぎる場合や、依存関係が不完全で確実な計画を立てられない場合は、説明を求めます。無人モードでは、明示された前提に基づいて作業を進めます。

ステップ 2：アプローチを計画する

永続的なアーキテクチャ上の判断を特定します。変更を吸収し、内部実装を露出させないデータモデル、API コントラクト、モジュール境界などが該当します（deep-modules を参照）。

複雑な作業の場合、偏りのない回答を得るため、コードベースの調査をサブエージェントに委任します。

調査（委任）

既存のシステム、パターン、統合ポイントについて、事実を確認する質問を 3～7 個作成します。それぞれ、現状の仕組みを尋ねる質問にしてください。質問から目標を推測できる場合は、書き直します。Issue に記載された既存実装への参照（ファイルパス、パッケージ、ライブラリのドキュメント）はそのまま渡し、Issue、PR、変更仕様へのリンクは決して渡さないでください。質問と参照情報だけを受け取る forge-scout サブエージェントに委任します。サブエージェントを利用できない場合は、ロールファイルを読み、そのルールに従って各質問に回答します。

サブエージェントに渡す入力： ロール：forge-scout、調査の質問、参照情報、コードベースへのアクセス権。 期待する出力： 質問ごとに 1 件の事実に基づく回答。ファイルパスとコード参照を含みます。

ランタイムがタスクごとのモデル選択に対応している場合は、スカウト作業に低コストで高速なモデルを優先します。

調査結果をもとに、次の内容を含むプランを作成します。

• 永続的な判断
• 構成の概要 — 影響を受ける必要なすべてのレイヤーを含み、検証ステップで終わる垂直的なフェーズ。フェーズ 1 で正常系のエンドツーエンド動作を実証し、以降のフェーズでは複雑さの軸を一度に 1 つずつ追加します。
• 作成または変更するファイル
• 対象範囲の境界（変更しない内容）

AskUserQuestion を通じてプランを提示します。コーディングを始める前にユーザーの確認を得ます。無人モードでは AskUserQuestion を省略し、そのまま進めます。

ステップ 3：機能ブランチを作成する

git fetch origin
DEFAULT_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD | sed 's@^refs/remotes/origin/@@')
git rev-list --count origin/$DEFAULT_BRANCH..HEAD   # 0 on a non-default branch → a worktree tool prepared it; stay on it

それ以外の場合は、フェッチしたデフォルトブランチから分岐します。デフォルトブランチには切り替えません。これにより、別の場所でデフォルトブランチがチェックアウトされているワークツリー内でも動作します。

git checkout --no-track -b <TYPE>/<ISSUE_NUMBER>-<BRIEF_DESCRIPTION> origin/$DEFAULT_BRANCH

プランファイルまたは自由形式のテキストを使用する場合（Issue 番号がない場合）は、説明的なスラッグ <TYPE>/<BRIEF_DESCRIPTION> を使用します。

ステップ 4：実装する

まず AGENTS.md を読みます。プロジェクトの規約に厳密に従ってください。

phase-execution に従って、垂直的なフェーズごとに作業を進めます。最初のフェーズの前に事前検証を行い、各フェーズ内でコードとテストを一緒に実施し、次のフェーズに進む前にフェーズゲートを通過します。フェーズゲートの条件は、テストが成功していること、新たな lint／型チェックの失敗がないこと、論理的にまとまった変更が 1 つコミットされていることです。

ステップ 2 のプランから逸脱した場合は、その理由とともに発生時点で記録します。PR には、そのすべてを記載します。

ステップ 5：パターンの一貫性を監査する

パターン（エラー処理、コンポーネント構造、API の規約など）を変更した場合は、古いパターンを使用している他のファイルをすべて grep で検索し、それらも更新します。文字列の一致だけでなく、パターンの形を監査してください。pattern-audit を参照してください。

ステップ 6：ドキュメントを更新する

動作や規約に変更があった場合は、docs/*.md と AGENTS.md を更新します。

ステップ 7：最終品質ゲートを実行する

すべてのプロジェクト品質チェックを実行します（AGENTS.md、プロジェクトのドキュメント、またはリポジトリ内のスクリプトから確認してください）。

• リント — 違反なし
• フォーマット — 違反なし
• 型チェック — エラーなし
• すべてのテストに合格
• 新規／変更コードのテストカバレッジ ≥ 90% — プロジェクトのカバレッジツールを実行します。カバレッジツールが設定されていない場合は、ユーザーに伝え、セットアップを提案してください。

問題を修正し、修正をコミットします。

ステップ 8：変更を実際に試す

exercise に従ってアプリを実行し、変更した経路を一度、さらに失敗ケースを一度試します。PR を作成する前に、見つかった問題をテストとともに修正してください。

ステップ 9：プッシュして PR を作成する

git push -u origin <BRANCH_NAME>

慣例的なコミットタイトルと、pr-body の本文を使って PR を作成します。理由は、リンクされた Issue がある場合はその問題説明から、リンクがない場合はコミット履歴から取得します。無人実行モードでは、前提とした事項を Notes に記載します。Issue がある場合はクローズしてください。

本文は、引用符付きヒアドキュメントを介して標準入力から渡してください。インラインの --body "..." では、複数行のテキスト、バッククォート、引用符が正しく扱われません。

gh pr create --title "<TYPE>(<SCOPE>): <DESCRIPTION>" --body-file - <<'PR_EOF'
<PR body>
PR_EOF

ステップ 10：要約する

ブランチ名、PR リンク、作成したコミット、変更したファイル、追加したテスト、更新したドキュメント、実施した動作確認の結果、保留事項を報告します。

ガイドライン

• コーディングの前に調査する — 方針を決める前にコードベースを調査します
• 不明点があれば尋ねる — 誤った実装をするより、確認するほうが適切です。無人実行では前提を明示してから進めます
• スコープを広げない — 依頼された内容だけを実装します

関連スキル

実装後： レビューを依頼する前に、自己レビューのため forge-reflect を使用します。 1 回の呼び出し： 実装とレビューを 1 つのステップで行うには、forge-ship を使用します。

使用例

/forge-implement 123
/forge-implement 123 -- keep the diff minimal and prefer existing UI patterns
/forge-implement --unattended 123
/forge-implement docs/roadmap.md
/forge-implement add a dark mode toggle to the settings page