tech-spec

Tech Spec スキル

トリガー

• キーワード：tech spec、technical specification、spec review、review spec、feature design

使用しない場合

• リクエストドキュメントの作成（/create-request を使用）
• コードの実装（feature-dev を使用）
• アーキテクチャに関するコンサルティング（/codex-architect を使用）

コマンド

コマンド	目的	タイミング
/tech-spec	技術仕様書の作成または更新	ファイルシステムの状態から作成／更新を自動判定します
/deep-analyze	仕様を深掘りし、ロードマップを作成	初期コンセプトの作成後
/review-spec	技術仕様書のレビュー	仕様の確認時

コンテキスト対応モード（アップサート）

完全な要件の説明なしで呼び出された場合、このスキルは references/native-feature-resolution.md にあるカスケード（このスキル独自のリファレンスであり、 意図的にコマンドを含みません）を使って、対象の機能を自動判定します。

このスキルには Bash(git:*) が許可されていますが、Bash(node:*) は許可されていません。そのため、リゾルバースクリプトは実行可能なコマンドではありません。また、実行できないコマンドを列挙したファイルをこのスキルから参照可能なグラフに含めることは、注釈の問題ではなく欠陥であるため、実行方法を説明する共有リファレンスへのリンクもありません。カスケードに必要なのは、$ARGUMENTS、git branch --show-current、git diff --name-only HEAD、および docs/features/* に対する Glob だけです。これらから4つのドキュメントソースセットや scan_error が得られるわけではありません。このスキルではどちらも使用しません。これらのセットが必要なスキル（/architecture、/tech-brief、/runbook、/ask）では、Bash(node:*) が許可されており、共有リファレンスを直接読み込みます。

標準的な探索は引き続き必要であり、1つのリテラルパスを試すだけでは不十分です。 仕様がフォルダーに分割されていたり、別の名前が付いていたりする可能性があります。このリポジトリにある docs/features/auto-loop-evolution/2-tech-spec/2-tech-spec.md が実例です。docs/features/<key>/ に対して Glob をこの順番で実行し、最初に見つかったものを採用します。

#	Glob	意味
1	docs/features/<key>/2-tech-spec.md	分割されていない標準仕様書
2	docs/features/<key>/2-tech-spec/2-tech-spec.md	分割された仕様書 — フォルダーにはライフサイクルのプレフィックスを、メインファイルには標準ファイル名を付けます（@rules/docs-numbering.md § Size Limit）
3	docs/features/<key>/2-tech-spec*.md。ただし、-fp-brief.md または -tech-brief.md に一致するものを除外	バリアント（2-tech-spec-v2.md）。この2つのサフィックスは仕様書ではないため除外します。同じ理由で scripts/config/doc-taxonomy.json にも同じ exclude_pattern があり、docs/features/seek-verdict/ には、この Glob が標準仕様書として返してしまう実例の 2-tech-spec-fp-brief.md があります。残った候補が2つ以上ある場合は、一致ではなく曖昧な状態です。1つを選ぶのではなく、その旨を報告して「Need Human」で終了してください

要件ドキュメント（1-requirements.md）も同じ3通りで解決しますが、サフィックスの除外は行いません。doc-taxonomy.json では exclude_pattern は tech-spec タイプにのみ設定されています。ここで要件ドキュメントにも適用すると、分類器に合わせるのではなく、分類器から外れてしまいます。Glob でエラーが発生した場合、または信頼度 low で解決された <key> が何にも一致しない場合は、「仕様書が存在しない」と同じではありません。どちらに該当するかを伝え、黙って作成モードに切り替えないでください。

4つ目の検索ではインテント成果物を解決します。機能ディレクトリ内の intent-<key>.md と完全一致するもののみを対象とし、ワイルドカードで選んではいけません。別途 Glob intent-*.md を実行するのは、余分なファイルやキーが間違ったファイルを検出するためだけです（報告してください。インテントとして採用してはいけません）。

ファイルシステムの状態	アクション
正規の探索で仕様書がちょうど1件見つかった	更新モード：そのファイルを読み取ります。探索で返されたパスを使い、リテラルの 2-tech-spec.md は使いません。前回の更新以降のコード変更を調査し、変更されたセクションを段階的に更新します
3つのグロブがすべて空	作成モード：テンプレートから docs/features/<key>/2-tech-spec.md に新しい仕様書を生成します
グロブ3が2件以上を返した	ゲート：人間の判断が必要 — 正規の仕様書が曖昧なため、候補を示します
機能を特定できなかった	ゲート：人間の判断が必要

作成モードで intent-<key>.md が存在しない場合は、まず /req-analyze にバンドルされている intent テンプレートを使って作成します。要件の明確化ステップでまとめた内容（制約のみ、60行以内）を記載し、その後に仕様書を作成します。存在する場合は、設計の前に読み取ります。

更新モードでは、直近のコード変更の影響を受けたセクションに重点を置きます（git diff を使って特定します）。変更のないセクションは保持します。intent-<key>.md が存在しない場合は、作成モードと同じ方法で作成します（1-requirements.md の §§ 1–2 があればそこから、なければ仕様書の要件概要から作成します）。これにより、intent の仕組みより前に作られた仕様書を持つ機能についても、next-step のアドバイザリを収束させられます。存在する場合は読み取ります。INV-* または非目標に矛盾する仕様書の各セクションは、ユーザーに明示すべき競合であり、取り繕ってはなりません。intent を仕様書に合わせて書き換えることも決してしてはなりません。intent の修正は、人間による再決定です。

ワークフロー

sequenceDiagram
    participant A as Analyst
    participant C as Codebase
    participant D as Document

    A->>A: 1. Requirement clarification
    A->>C: 2. Code research
    C-->>A: Related modules
    A->>A: 3. Solution design
    A->>A: 4. Risk assessment
    A->>A: 5. Work breakdown
    A->>D: 6. Output document

仕様書の構成

1. 要件概要（問題 + 目標 + スコープ）
2. 既存コードの分析
3. 技術的な解決策（アーキテクチャ + データモデル + API + コアロジック）
4. リスクと依存関係
5. 作業の内訳
6. テスト戦略
7. 未解決の質問

作成時の行数予算

仕様書は、作成時に短く保つのが最も簡単です。作成後に長さを制限すると、分割するか削減する必要があり、どちらの場合も、作成時に予算を意識していれば避けられたレビューが1回増えます。

行数（wc -l）	作成時の目安
≤ 300	目標です。これを目指してください
301–400	許容範囲です。追加する前に削ってください
> 400	一貫性の例外について、文書内で明記するか、記述前に削減または分割してください。「書くスペースが足りなくなった」は例外ではありません

例外は、これらのセクションが、分けて読むよりも一体として読むほうがよい一つの論旨である理由を示す文です。明記されていない場合、400行を超える仕様書は予算超過です。@rules/docs-numbering.md の § Size Limit に従い、まず削減し、次に統合し、それから分割します。

省く内容：検討して却下した代替案（セクションにはせず、各案を1行で記載）、設計がどのように変わったかの履歴（これは記録に記載します）、およびコードのほうが文章より正確に示せる内容です。

更新モードでは、コードによって古くなったセクションは注釈を付けずに削除します。その場で書き換えることで、仕様書を現行の正式な情報源として保てます。「以前は……」という注記を重ねると、本来の役割ではない記録になってしまいます。

出力

Overview、Requirements、Architecture、Implementation plan、Work breakdown、Testing strategy、Open questions の各セクションを含む番号付きの技術仕様書。

検証

• 解決策がすべての要件項目を満たしている
• アーキテクチャ図に Mermaid を使用している
• リスクに軽減策がある
• 作業を追跡可能な項目に分割できる
• 作成時の行数予算内であるか、例外を文書内で明記している

参考資料

• references/template.md - 仕様書のテンプレートとレビュー観点

ファイルの場所

docs/features/{feature}/
├── 2-tech-spec.md    # Technical spec (numbered per docs-numbering rule)
├── requests/         # Request documents
└── README.md         # Feature description

例

Input: /tech-spec "Implement user asset snapshot feature"
Action: Requirement clarification -> Code research -> Solution design -> Output document

Input: /review-spec docs/features/xxx/2-tech-spec.md
Action: Read -> Research -> Review -> Output report + Gate