📐 ドキュメントは「参照して詳細化する」もの
壁打ち・規模判定が終わったら、いよいよステアリングの中身を作ります。ステアリング駆動開発の中核は以下の階層です。
docs/specs/（全体仕様 = 北極星・参照用）
│
│ 参照・抽出
↓
.steering/[タスク]/（詳細仕様 = 実装入力）
│
│ TDD 実装
↓
コード完成docs/specs/ は「そのまま実装する」ものではなく、「参照して詳細仕様を作成」するためのもの です。全体仕様を読み込み、今回のタスクに必要な情報だけを抽出して .steering/[タスク]/ に詳細化します。
🗂️ M 規模 / L 規模のファイル構成
| ファイル | M 規模 | L 規模 | 参照スキル |
|---|---|---|---|
requirements.md | ✅ 詳細要求 | ✅ PRD | prd-writing |
design.md | ✅ 詳細設計 | ✅ 機能設計書 | functional-design |
tasklist.md | ✅ | ✅ | steering |
decision.md | ✅ ADR 形式 | ✅ ADR 形式 | - |
architecture.md | ❌ | ✅ 技術仕様書 | architecture-design |
repository-structure.md | ❌ | ✅ 構造定義 | - |
development-guidelines.md | ❌ | ✅ ガイドライン | - |
glossary.md | ❌ | ✅ 用語集 | glossary-creation |
CTS-EC で使っているテンプレートは .claude/skills/steering/templates/ にあり、最大 200 行弱のひな形から埋めていきます。
📋 requirements.md の必須セクション
M 規模でも L 規模でも 制約事項セクションは必須です。.NET 開発なら STG DB 接続制約、フロントエンドなら E2E シナリオ番号（AT-*）などを明記します。
L 規模（PRD）の必須セクション：
- 概要（目的、背景、スコープ）
- ユーザーストーリー
- 機能要件（詳細、優先度）
- 非機能要件（パフォーマンス、セキュリティ）
- 制約事項（技術的、ビジネス的）
- 成功基準（KPI、受け入れ条件 AT-*）
- リスクと軽減策
🏛️ design.md は「参照実装テーブル」で差別化する
ステアリング作成で 最も差がつくのが design.md です。ポイントは「新規に書くコンポーネント設計」より、§ 参照実装テーブルを必ず持つことです。
| ファイル | パターン | 今回の採用部分 |
|---|---|---|
dotnet/src/.../EmbeddingStore.cs | Store + Provider | Store 構造を踏襲 |
dotnet/src/.../ProductService.cs | Service + Handler | CommandHandler パターン |
tests/.../EmbeddingTests.cs | xUnit + Theory | テスト構造を流用 |
実装開始前に Phase 0（参照実装レビュー）でこの全ファイルを Read します。これをスキップすると「既存パターンと異なるコードを書く → バグ・不整合 → 出戻り」が繰り返し発生します。
🚨 CTS-EC の教訓：過去に参照実装を確認せずに独自パターンで実装した結果、 本番コードと設計が崩れるケースが繰り返し発生 しました。「既存の本番コードこそ最も信頼できるリファレンス」を原則としています。
🧱 TDD タスク分解：2 ステップ必須
tasklist.md では すべての実装タスクを「テスト作成 → 実装」の 2 ステップに分解 します。
❌ 禁止される形式
| 1.1 | YahooOAuth API 実装 | ❌ |✅ 正しい形式
| 1.1a | YahooOAuthService の Constructor テストを書く | ❌ | TDD: Red |
| 1.1b | YahooOAuthService の Constructor を実装 | ❌ | TDD: Green |
| 1.2a | Authorize メソッドの正常系テストを書く | ❌ | TDD: Red |
| 1.2b | Authorize メソッドを実装 | ❌ | TDD: Green |
| 1.3 | Program.cs に DI 登録を追加 | ❌ | |「テスト」と「実装」は別タスクです。1 タスク = 1 つの明確なアウトプットを守ります。
⏱️ タスク粒度：2〜5 分原則
タスクリストの粒度はコンテキスト管理と進捗可視性を両立するため、2〜5 分を推奨しています。
| 単位 | 目安時間 | 例 |
|---|---|---|
| 推奨 | 2〜5 分 | Constructor 実装、単一メソッドのテスト |
| 上限 | 15 分 | メソッド 1 つの実装（複数処理込み） |
| 超過時 | 必須分割 | 機能単位 → サブタスク化（テスト→実装→DI 登録） |
チェックボックス更新が 5 分以上空いたら、タスクが大きすぎる証拠です。即サブタスクに分割します。
📊 進捗サマリーとフェーズ検証記録
tasklist.md の冒頭には 進捗サマリーとフェーズ検証記録の 2 テーブルを置きます。これにより /resume 時に「どこまで進んでいるか」「どの検証が未実施か」が一目でわかります。
## 進捗サマリー
| Phase | 内容 | 状態 | 完了 |
| ------- | -------------------- | --------- | ------ |
| Phase 0 | 参照実装レビュー | ✅ 完了 | 3/3 |
| Phase 1 | OAuth コア実装 | 🟡 進行中 | 6/10 |
| Phase 2 | 店舗連携・移行 | ❌ 未着手 | 0/8 |
| - | 最終: 品質検証 | ❌ 未着手 | 0/5 |
## フェーズ検証記録
| Phase | /test | validator | 完了日 |
| ------- | --------- | --------- | ---------- |
| Phase 0 | - | - | 2026-04-18 |
| Phase 1 | ✅ 全パス | ✅ PASS | 2026-04-20 |
| Phase 2 | - | - | - |🧩 Phase 0 は「参照実装レビュー」専用
CTS-EC では tasklist.md の Phase 0 を「参照実装レビュー」に固定 しています。実装開始前の必須ゲートです。
| # | タスク | 状態 |
| --- | ------------------------------------------------------------ | ---- |
| 0.1 | design.md §参照実装の全ファイルを Read | ❌ |
| 0.2 | 参照実装と今回の実装の対応表をユーザーに報告 | ❌ |
| 0.3 | 「既存の○○と同一パターンで実装する」を明示してからコーディング | ❌ |この 3 タスクが ✅ になるまで Phase 1 に進めません。
🏗️ L 規模の 4 つの追加ドキュメント
L 規模で追加される 4 つのドキュメントは、タスク固有ではなく後から参照される長寿命ドキュメント です。
| ファイル | 主な内容 | 参照される場面 |
|---|---|---|
architecture.md | テクノロジースタック、アーキテクチャパターン、データ永続化戦略、セキュリティ、パフォーマンス要件 | 設計レビュー、類似ステアリング作成時 |
repository-structure.md | 追加・変更されるディレクトリとファイル配置規則 | 実装時、コードレビュー時 |
development-guidelines.md | このタスク固有のコーディング規約・Git 運用・テスト戦略 | 実装時 |
glossary.md | ユビキタス言語の用語集（ドメイン用語 + 技術用語） | 全工程、全レビューで参照 |
glossary.md は .claude/skills/steering/templates/glossary-guide.md に用語の抽出基準があります。**「壁打ちで新しい用語が出てきた = L 規模シグナル」**の基準もここで判断します。
✅ decision.md は ADR 形式で
tasklist 中に発生する設計判断は decision.md に ADR 形式で残します。
# 設計判断記録
## ADR-001: OAuth ライブラリ選定
**日付:** 2026-04-20
**状態:** 採用
### コンテキスト
- Yahoo OAuth の .NET 実装が必要
- 社内に OAuth2.0 の既存実装あり（CognitoAuth）
### 選択肢
| # | 選択肢 | メリット | デメリット |
| - | ------------------- | -------------- | -------------- |
| A | 自前実装 | 制御しやすい | 保守負担大 |
| B | IdentityServer 委譲 | 実績あり | 学習コスト |
| C | Microsoft.Identity | .NET 標準 | Yahoo 未対応 |
### 決定
**選択肢 B を採用**
### 理由
既存の CognitoAuth が IdentityServer ベースで、運用パターンが確立されているため。壁打ち段階の brainstorm.md との違いは、「ステアリング固有・作業中の判断」 を記録する点です。プロジェクト全体に永続化すべき判断は /steering-complete 時に docs/adr/ に昇華します。
🚫 ステアリング作成でやってはいけないこと
docs/specs/の全体仕様を「コピペ」して.steering/を作る（参照して抽出するのが目的）- 参照実装テーブルを持たない design.md で実装開始する
- tasklist.md を 1 タスク = 1 機能単位で切る（2 ステップ分解が必須）
- 制約事項セクションを省略する（STG DB 接続、E2E シナリオ番号など）
- Phase 0（参照実装レビュー）をスキップして Phase 1 に進む
📚 シリーズ記事
| # | タイトル | 内容 |
|---|---|---|
| 1 | 概要 | ステアリング駆動開発の全体像 |
| 2 | 壁打ち・規模判定編 | 壁打ちの進め方、ADR の書き方、規模判定の基準 |
| 3 | ステアリング作成編（本記事） | M/L 規模のドキュメント作成、TDD タスク分解 |
| 4 | 実装・完了編 | TodoWrite 連携、進捗管理、アーカイブ運用 |
| 5 | コンテキスト設計編 | AI に渡すコンテキストの最適化、skills 設計 |
| 6 | 品質ゲート編 | doc-reviewer、テスト品質チェック、受入テスト |
| 7 | Claude Code ベストプラクティス | CLAUDE.md 設計、hooks、commands、rules、skills |
| 8 | Agent Teams 編 | agents 定義、チーム構成、マルチエージェント協調 |
| 9 | Remote Control 編 | スマホ・Web から CLI セッションを操る席拘束からの解放 |
🔗 関連記事
- ステアリング駆動開発とは：概要 — シリーズ全体の導入
- 壁打ち・規模判定編 — ステアリング作成の前工程
- Claude Code 7層ハーネスエンジニアリング — 実装時の品質ゲート