dev-story

!bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys automation,workflow,qa.level,gate_level,engine_values,specialists,perf_budgets,system_overrides

上記で解決済みです。そのまま使用してください。ブロックがない場合は、 .claude/docs/config-resolution.md のデフォルト値を使用します。

質問ツールで尋ねてください。質問ツールがない場合は、選択肢に番号を付けて列挙し、回答を待つためにターンを終了してください。質問をスキップしたり閉じたりしただけでは回答になりません。プレーンテキストでもう一度尋ねてください。

開発ストーリー

1つのストーリーを実装します。開始できることを確認し、ステータスを「進行中」に変更して、ストーリーに基づく簡潔なブリーフとともに、適切なプログラマーエージェントにコード作成を引き継ぎます。その後、結果を解析できることと内容が適切であることを確認し、引き継ぎます。

書き込み対象（それぞれ、対象名を明示して確認を求めてから書き込みます）：ストーリーの Status、Last Updated、## Files、およびその production/sprint-status.yaml エントリーです。プログラマーエージェントは、コードルートとテストルートの下にコードとテストを書き込みます（.claude/docs/code-root-resolution.md）。セッションチェックポイントとエビデンススタンプは、確認なしで書き込まれます。 次の手順： /story-done [story-path]。standard と full では、先に /code-review [files] を実行してください。

確認の手順は .claude/docs/automation-modes.md に従います（collaborative は常に確認し、guided は重要な選択で確認し、autonomous は記録して続行します。automation_always_ask カテゴリーは常に確認します）。

チェックリスト（コピーして、進行に合わせてチェックしてください）：

- [ ] Phase 1: story found, tier resolved
- [ ] Phase 2: prerequisites checked (ADR, manifest, dependencies)
- [ ] Phase 3: story marked In Progress (one ask)
- [ ] Phase 4: programmer and engine specialist chosen
- [ ] Phase 5: work handed out with a full brief
- [ ] Phase 6: finished? parse check, run and look, one Run result line
- [ ] Phase 7: summary, ## Files, checkpoint, closing block

フェーズ 1：ストーリー

スキル名の後に入力されたテキストは、ストーリーのパスです。何も入力されていない場合は、production/session-state/active.md のチェックポイントで指定されたストーリーを取り上げ、次のように確認してください。 「[title] の作業を続けます。よろしいですか？」該当するストーリーがない場合は、bash .claude/scripts/story-facts.sh --all の TODO 行を選択肢として、「どのストーリーを実装しますか？」と尋ねてください。production/epics/ にストーリーファイルが1つもない場合は、次のメッセージを表示して停止してください。 「production/epics/ にストーリーが見つかりません。作成するには /create-stories [epic-slug] を実行してください（standard と full で、エピックがまだない場合は先に /create-epics を実行してください）。」

bash .claude/scripts/story-facts.sh <story-path> で、ストーリーの種類、レイヤー、TR-ID、ADR、依存関係がわかります。その後、ストーリー全体を読んでください。

ティア。 ストーリーのシステムに対応する workflow を使用します。GDD ファイル名のベース名をキーにします（GDD: のパスが design/gdd/<stem>.md の場合は <stem>。GDD パスがない場合に限り、TR-ID の [system] を使用します）。そのシステムの system_overrides 行があればその値を、なければプロジェクトの値を使用します。最初の返信で、Tier: workflow [value] の形式で伝えてください。この値のみがフェーズ 2 の列と最後の Next 手順を決定します。rigor や qa.level は使用しないでください。

フェーズ 2：開始できますか？

入力	full	standard	minimal
TR レジストリ docs/architecture/tr-registry.yaml	不在：停止、「/architecture-review を実行してブートストラップしてください」	任意	想定されていません
ストーリーで指定された ADR	不在、Proposed、Deprecated、または Superseded：停止	同様。ただし、ストーリーで指定されている場合のみ	同様。ただし、ストーリーで指定されている場合のみ
管理マニフェスト docs/architecture/control-manifest.md	不在：警告して続行	不在：警告して続行	想定されていません

ADR フィールドに N/A — [reason] と記載されたストーリーは、ADR を指定していません。

ADR。 bash .claude/scripts/adr-status.sh <ADR id> でステータスと version を確認できます。停止時のメッセージ：Proposed — 「ADR-NNNN はまだ Proposed です。実装前に /architecture-decision accept ADR-NNNN で承認してください。」Deprecated または Superseded — 「ADR-NNNN は [status] です。実装前に、ストーリーの ADR フィールドを編集して [successor] を指定してください。/create-stories は既存のストーリーを書き換えません。」 NOT_FOUND — 「ADR ファイルが見つかりません。/architecture-decision を実行するか、 ストーリーの ADR フィールドを修正してください。」

ADR を開かないでください。 プログラマーが読むのは、ストーリーの ADR Decision Summary と Implementation Notes です。ADR の version とストーリーの ADR Version を比較します。

• 一致する場合、ストーリーに ADR Version がない場合（スタンプを記入する前に作成されたもの）、または両方が unversioned の場合は、ストーリーを信頼します。後者 2 つは要約に「要約は未検証のまま信頼」と記載します。
• 異なる場合、または ADR が unversioned なのにストーリーに日付が記載されている場合は、 references/version-mismatch.md を読みます。一致していれば、読み込む必要はありません。

スタンプがないことを古いスタンプとして扱わないでください。不明な場合はストーリーを優先します。ずれは後で /story-readiness と /code-review のチェックで検出されます。

マニフェスト。 存在する場合は、Manifest Version の行とストーリーのバージョンを比較します。 異なる場合は、references/version-mismatch.md を読みます。

依存関係。 ストーリーの Depends on 行にある各パスについて、 bash .claude/scripts/story-facts.sh <path> を実行します。COMPLETE でない場合は、「[this story] は [dependency] に依存していますが、そのステータスは Complete ではなく [status] です。どのように進めますか？」 と尋ねます。選択肢：そのまま進める — リスクを受け入れます / 停止する — 先に依存関係を完了します / 完了済みですが、ステータスが更新されていません — Complete に設定します。 停止する場合：ストーリーは BLOCKED です（フェーズ 7）。エージェントは起動しません。ステータスを変更する場合は、まず「[path] の Status を Complete に設定してもよいですか？」と尋ねます。そのまま進める場合は、逸脱事項に記載します。 NOT_FOUND の場合は、「依存ストーリーが見つかりません：[path]」と警告します。

上記のいずれかで停止した場合、エージェントは起動しません。フェーズ 7 に進み、BLOCKED チェックポイントを記録します。

フェーズ 3：In Progress に設定する

エージェントを起動する前に、一度だけ次のように尋ねます：「このストーリーを In Progress に設定してもよいですか？Status と Last Updated を [story path] で更新し、最後に変更したファイルをそのストーリーの ## Files に記載します。」ファイルが存在しない場合は、質問にスプリントファイルを含めません。質問の前に、次に行う作業を伝えます。返信の最後に質問を置きます。承諾された場合：

• bash .claude/scripts/md-section.sh set-field <story> Status "In Progress" を実行し、続けて set-field <story> "Last Updated" <YYYY-MM-DD> --after Status を実行します。minimal では、進捗を記録するファイルはストーリーファイルのみです。
• production/sprint-status.yaml：このストーリーのエントリーに status: in-progress を設定し、 トップレベルの updated を今日の日付にします。ファイルがない場合は、Sprint status not updated: production/sprint-status.yaml absent と伝えます。

拒否された場合：どちらも変更せず、要約に Story not marked In Progress — declined と出力して、続行します。

フェーズ 4：担当者を決める

Config/Data ストーリーにはエージェントは不要です。 値の変更を変更前 → 変更後の形式で示し、「[data file]に書き込んでもよいですか？」と尋ねて、編集します。フェーズ 6 に進みます。

ストーリー	プログラマーエージェント
Foundation レイヤー、すべてのタイプ	engine-programmer
Type UI	ui-programmer
Type Visual/Feel	gameplay-programmer
Core または Feature、ゲームプレイ	gameplay-programmer
Core または Feature、AI またはパスファインディング	ai-programmer
Core または Feature、ネットワーク	network-programmer

すべてのコードストーリーには、エンジン専門家が必要です。 上記の specialists 行から、code（specialists.code、言語の専門家。engine.name では判別できない Godot C# プロジェクトと GDScript プロジェクトを見分けます）に加えて、ストーリーがシェーダーまたはマテリアルに関係する場合は shader、UI ストーリーの場合は ui を指定します。code が unset の場合は、汎用エンジン専門家である primary を指定します。記憶を頼りに専門家を選ばないでください。プロジェクトが選んだ専門家は、この行に記載されています。すべての値が unset で、primary もない場合は、「No engine specialist configured」と伝え、専門家を割り当てずに進めます。

フェーズ 5：作業を割り当てる

実装をプログラマーエージェントに依頼します。ブリーフではファイルを指し示し、ドキュメント全体を貼り付けてはいけません。

• 目的： [story path] を、受け入れ基準に沿って、Out of Scope の範囲内で実装します。
• 参照資料：
  1. ストーリーファイル。基準、範囲、および QA テストケースが記載されています。
  2. 確認対象の各 TR-ID（TR-[system]-NNN）：docs/architecture/tr-registry.yaml 内で id: <TR-ID>\s*$ に一致する行を参照します。正とするのは requirement のテキストであり、ストーリー内で引用されたテキストではありません。
  3. ADR のガイダンス（インライン）：ストーリーの ADR Decision Summary と Implementation Notes を参照します。ADR のパスは参照しないでください。
  4. コントロールマニフェストの [Layer] Layer Rules（セクション単位）。
  5. project.yaml の naming.* と、上記の perf_budgets 行。
  6. ストーリーの Test Evidence セクションにあるテストファイルのパス。
• テスト： Logic および Integration ストーリーでは、qa.level に応じて対応します。
  • minimal：「このストーリーのテストファイルは作成しないでください。qa.level: minimal ではテストエビデンスは免除されています。」と伝えます。省略された行と、伝え忘れた行はエージェントには区別がつかないため、必ず明示します。
  • standard：「コードと一緒に、[path] にテストを書いてください。各受け入れ基準に、少なくとも 1 つのテスト関数が必要です。」と伝えます。命名規則はエンジンごとに .claude/rules/test-standards.md に従います。ランダムシード、時間依存のアサーション、外部 I/O は使用しません。
  • full：同じ内容を伝え、さらに「すべての基準を網羅してください。未テストの基準が 1 つでもあると、/story-done で処理が停止します。」と伝えます。
• 出力： 作成または変更したファイル、作成したテスト関数、質問またはブロッカー、および作業が完了したかどうか。
• 制約： コードの記述は解決済みのコードルート配下に限り、テストの記述はテストルート配下に限ります。コードルートが未解決の場合は何も書かず、その旨を報告します。ストーリーの範囲外のファイルには触れず、必要な場合は代わりにその必要性を報告します。公開 API にはドキュメントコメントを付けます。ADR で扱われていないアーキテクチャ上の選択は、計画を報告し、独断で決定しないでください。一度しか使わないヘルパーや抽象化は作成しません。起こり得ないケースに対するエラー処理は追加しません（入力とデータファイルの境界でのみ検証します）。汎用ロジックを使用し、テストに合格するためだけに値を特別扱いしてはいけません。

ブリーフに含まれていない内容は、両者に伝えます。 フェーズ 2 で見つからなかった入力（TR レジストリ、ADR、マニフェスト）はブリーフから除外し、エージェントには「No [input] is passed — it does not exist at this tier; do not go looking for it」と伝えます。作業を割り当てる直前に、ユーザーには次の 1 行を伝えます：Briefing omits: [inputs] — implementing against the acceptance criteria and the [GDD | brief].

プログラマーから報告があったら、エンジンの確認を専門家に依頼します。 ブリーフ：変更されたファイルについて、docs/engine-reference/<engine>/ を参照し、[engine + version] におけるエンジン API の使用方法に誤りがないか、または変更されていないかを確認します。ファイル、行、問題、修正方法の一覧を返し、編集は行いません。受け入れ基準に影響する問題は 1 回だけプログラマーに差し戻します。それ以外は要約に記載します。

フェーズ 6：結果を確認する

エージェントは完了しましたか？ 途中で止まった、制限に達した、または報告が作業の途中で終わっている場合、ストーリーは**未完了（INCOMPLETE）**です。その時点で存在するものを列挙し、問題点を示し、エージェントの作業を再開するか尋ねてください。「Implementation Complete」とは決して記載せず、ステータスもそのままにしてください。

報告どおりに作成されていますか？ まず成果物を確認してください。エージェントの報告に記載されているファイルがディスク上に存在しなければ、報告がどれほど流暢でも、そのステップは失敗です。エージェントの作業を再開し、欠落しているファイルを示してください。報告が BLOCKED、エラー、または「cannot complete」の場合は、その旨をすぐに伝え、ブロックされている範囲を超えて先に進まず、部分的な報告を行ってください （.claude/docs/error-recovery-protocol.md）。スコープが大きすぎる場合は、/create-stories を使って分割してください。ADR とストーリーが食い違う場合は、矛盾を報告してください。決して推測してはいけません。

テストはありますか？ qa.level: standard および full で、Logic または Integration ストーリーの場合は、Test Evidence パスにファイルがあるか確認してください。ファイルがない場合、型ごとの BLOCKING レベルでは gate_level 行に「story unverifiable — test required before /story-done」と記載します。ADVISORY では推奨事項として記載します。minimal では確認項目はありません。テストは免除されています。

パースできますか？ 終了コードで判断できるチェックを実行し、コマンド、終了コード、エラー行を報告してください。

• Godot： godot --headless --path . --import を 1 回実行した後、godot --headless --path . -s res://.claude/scripts/godot-parse-check.gd -- res://<変更した各 .gd> を実行します。 終了コード 1 はスクリプトが読み込めなかったことを意味します。該当する PARSE FAIL: 行にファイル名が示されます。--check-only は決して使わないでください。また、--import だけではパースチェックになりません。ファイル名に godot と記載されている場合は、commands.test に記載された実行ファイルを使ってください（bash run-tests.sh のようなラッパーはエディターではありません）。それ以外の場合は engine.path、さらにそれがなければ godot を使います。ディスク上を探してはいけません。この 3 つのいずれも実行できない場合、チェックは未検証です。
• Unity、Unreal： references/engine-checks.md を確認してください。
• エンジンの実行ファイルがない場合： parse NOT VERIFIED — engine binary not available。コードを読んだだけでパースできると判断してはいけません。

実行して確認する（.claude/docs/run-and-observe.md）。プレイヤーが目にするストーリー（すべての Visual/Feel および UI ストーリーと、表面化するその他のストーリー）では、ストーリーで変更したシーンを直接起動し、スクリーンショットを production/qa/evidence/[story-slug]/ に直接保存してください（[story-slug] は .md を除いたストーリーファイル名です。先に mkdir -p でフォルダーを作成してください）。次に、bash .claude/scripts/review-receipts.sh hash <変更した各ファイル> > production/qa/evidence/[story-slug]/stamp.txt を実行して証跡を記録し、画像を開いて基準と比較してください。qa.level: minimal でも免除されません。次のうち、プレーンテキストで始まる行を必ず 1 行だけ報告してください（太字にしないでください。/story-done は書かれたとおりに読み取ります）。

• Run result: OBSERVED — <画面に表示されたもの>。保存したパスを含めます。
• Run result: NOT VERIFIED — <理由>（エンジンがない、何もキャプチャされていない）。デフォルトのゲートレベルでは、Visual/Feel または UI ストーリーの /story-done がブロックされます。
• Run result: N/A — <理由>。観察できるものがないストーリーの場合に使います。理由には、観察できない理由を記載してください（/story-done では「Logic ストーリーだから」は受け付けられません）。

Visual/Feel 基準のうち、感覚に関する部分（タイミング、重み）だけは静止画では確認できないため、/team-qa に DEFERRED されます。

このスキルでは、PATH 上の godot は事前承認されています。engine.path 経由のエンジン実行、または commands.test に記載された実行ファイルを使う場合は、ユーザーが一度承認するか、.claude/settings.local.json に Bash(<that executable> *) を追加する必要があります。

フェーズ 7：要約、ファイル、チェックポイント

## Implementation Complete: [title]

**Files changed**:
- `[code root path]` — created / modified ([what])
- `[test path]` — [N] test functions
**Test evidence**: waived at `qa.level: minimal` — no test was required or written   (Logic/Integration at minimal, instead of the test line)
**Verification**: [command] — [exit code and result | parse NOT VERIFIED — <reason>]

**Acceptance criteria**:
- [x] [criterion] — [file:function | test name | OBSERVED in <image path>]
- [ ] [criterion] — DEFERRED: feel, needs a playtest
**Deviations**: [None | files outside scope, an accepted dependency or version risk]
**Engine risks**: [None | the specialist's findings]
**Blockers**: [None | each]

qa.level: standard と full では、次の文を追加します。「/story-done の前にテストスイートを実行し、新しいテストが成功することを確認してください。/story-done はテストファイルの存在を確認するだけで、テストは実行しません。」minimal では追加しません。実行するテストがないためです。Visual/Feel または UI のストーリーで、画像が保持されていない場合は、次の文を追加します。「/story-done の前に production/qa/evidence/[story-slug]/ 内に保持されたスクリーンショットが必要です」（Visual/Feel の場合は、production/qa/evidence/[story-slug]-evidence.md 内のサインオフも必要です）。

## Files。 セクションの本文を、Phase 3 の依頼どおり、変更したコードファイルとテストファイルのリスト（1 行に 1 ファイル）に置き換えます。リストを標準入力で渡して、bash .claude/scripts/md-section.sh replace <story> "Files" を実行します。そのようなセクションがないストーリーでは、ファイルを編集して末尾に ## Files とリストを追加します。シェルコマンドは使用しません（シェルによる書き込みではプロジェクトの書き込みチェックを通過しないためです）。Phase 3 の依頼が断られていた場合は、この手順を省略します。

チェックポイントは、どの結果の場合も作成します。ブロックを bash .claude/scripts/session-state.sh checkpoint に渡すと、古いチェックポイントが置き換えられます。

**Updated:** [date]
**Branch:** `[current git branch]`
**Current task:** /dev-story — [story path] ([title])
**Next step:** [the Next step below]
**Blocked on:** [nothing, or the blocker]
**Files in progress:** [changed files, comma-separated]
**Run result:** [OBSERVED — … | NOT VERIFIED — … | N/A — …, as in the closing block: /story-done reads it here]
**Open questions:** [none, or one line each]

実行時の最後の返信は、このブロックで終わらせます。 Run result: の行を出力するのはここだけです。返信内のほかの場所には出力しないでください。Next step は、Phase 1 で示したティア（rigor や qa.level ではなく、workflow の行）に従います。Next step：minimal では /story-done [path]。standard と full では /code-review [files]、続けて /story-done [path]。INCOMPLETE：再開するには /dev-story [path]。BLOCKED：ブロックを解除するためのアクション（/architecture-decision accept ADR-NNNN、完了させる必要がある依存関係、レビューが必要な diff）。

Story: [path] — [Implemented | INCOMPLETE — <breakage> | BLOCKED — <reason>]
Run result: [OBSERVED — … | NOT VERIFIED — … | N/A — …]
Next step: [Implemented, Tier: workflow minimal → /story-done [path] | Implemented, Tier: workflow standard or full → /code-review [changed files], then /story-done [path] | INCOMPLETE → /dev-story [path] to resume | BLOCKED → the unblocking action]