---
description: プロジェクト全体のステアリングドキュメントを作成・更新
---

# プロジェクト全体のステアリングドキュメント管理

このコマンドは、プロジェクト全体の永続的なコンテキスト（プロダクト方針、技術スタック、プロジェクト構造）をステアリングドキュメントとして管理します。

**重要**: 全ての `/sdd:*` コマンドは自動的にステアリングドキュメントを読み込み、プロジェクトの一貫性を保ちます。

## 実行手順

### 1. モード判定

`specs/_steering/` ディレクトリの状態を確認：

- **Bootstrap Mode（初期作成）**: ディレクトリが存在しないか、コアファイルが不足
- **Sync Mode（更新）**: 全てのコアファイルが存在

**コアファイル**:
- `product.md` - プロダクト方針、ターゲットユーザー、ビジネス目標
- `tech.md` - 技術スタック、アーキテクチャパターン、開発標準
- `structure.md` - プロジェクト構造、命名規則、コード組織原則
- `principles.md` - 開発原則（TDD、SOLID、TypeScript固有の原則など）

### 2. Bootstrap Mode（初期作成）

#### 2.1 既存プロジェクト情報の収集

以下の情報を収集してステアリングドキュメント生成に活用：

**プロダクト情報**:
- `README.md` の存在確認と内容読み取り
- パッケージマニフェスト（`package.json`, `pyproject.toml`, `Cargo.toml` など）からプロジェクト名と説明を抽出

**技術スタック情報**:
- `package.json` - Node.js依存関係、スクリプト、エンジンバージョン
- `tsconfig.json` / `jsconfig.json` - TypeScript/JavaScript設定
- `pyproject.toml` / `requirements.txt` - Python依存関係
- `Cargo.toml` - Rust依存関係
- `go.mod` - Go依存関係
- `.ruby-version` / `Gemfile` - Ruby依存関係
- ビルドツール設定（`vite.config.ts`, `webpack.config.js`, `next.config.js` など）
- データベース関連（`prisma/schema.prisma`, ORM設定など）

**プロジェクト構造情報**:
- ルートディレクトリの構造（`ls -la`）
- 主要ディレクトリ（`src/`, `lib/`, `app/`, `tests/` など）の存在確認
- ファイル命名パターンの分析（kebab-case, camelCase, snake_case）

**注意**: ファイルが見つからない場合はスキップし、テンプレート構造で生成

#### 2.2 ディレクトリ作成

```bash
mkdir -p specs/_steering
```

#### 2.3 ステアリングドキュメント生成

以下の3つのファイルを生成（収集した情報を反映）：

##### `specs/_steering/product.md`

```markdown
# Product Overview

## Product Purpose

[プロジェクトの目的]
- README.mdやpackage.jsonの説明から抽出
- 存在しない場合はプレースホルダー

**Vision (North Star)**:
[プロダクトのビジョン]

**解決する問題**:
- [課題1]
- [課題2]

## Target Users

**Primary Archetype**: [主要ユーザー像]
- [特徴1]
- [特徴2]

**ニーズと課題**:
- **ニーズ**: [ニーズ]
- **課題**: [課題]

## Key Features

このプロジェクトが提供する主要機能：

1. **[機能カテゴリ1]**: [説明]
2. **[機能カテゴリ2]**: [説明]

## Business Objectives

- **[目標1]**: [説明]
- **[目標2]**: [説明]

## Success Metrics

**Quantitative Metrics**:
- **[指標名]**: [測定方法]

**Qualitative Metrics**:
- **[指標名]**: [評価基準]

## Product Principles

1. **[原則1]**: [説明]
2. **[原則2]**: [説明]

## Non-Goals / Guardrails

このプロジェクトは以下の領域には**意図的に関与しない**：

- **[非対象1]**: [理由]
- **[非対象2]**: [理由]
```

##### `specs/_steering/tech.md`

```markdown
# Technology Stack

## Architecture

[システムアーキテクチャの概要]
- 既存プロジェクト構造から推測
- モノリス/マイクロサービス/JAMstack など

## Core Technologies

### Primary Language(s)
- **Language**: [検出された言語]
- **Runtime**: [検出されたランタイム]
- **Framework**: [検出されたフレームワーク]

### Key Dependencies/Libraries

[package.jsonなどから抽出した主要ライブラリ]

## Development Standards

### Type Safety
[型安全性に関する方針]
- TypeScript strict mode の使用状況
- 型定義の要求レベル

### Code Quality
[コード品質ツール]
- ESLint, Prettier, Ruff などの設定状況

### Testing
[テスト戦略]
- テストフレームワーク（Jest, pytest など）
- カバレッジ要求

## Development Environment

### Required Tools
[必要なツールとバージョン]
- Node.js, Python, Rust などのバージョン要求
- package.jsonのenginesフィールドから抽出

### Common Commands
```bash
# Dev: [開発サーバー起動コマンド]
# Build: [ビルドコマンド]
# Test: [テストコマンド]
```

## Key Technical Decisions

[重要な技術的決定とその理由]

1. **[決定事項1]**:
   - **理由**: [理由]
   - **代替案**: [検討した代替案]
   - **トレードオフ**: [トレードオフ]
```

##### `specs/_steering/structure.md`

```markdown
# Project Structure

## Directory Organization

```
[プロジェクト名]/
├── [検出されたディレクトリ構造]
├── specs/
│   └── _steering/          # ステアリングドキュメント
└── ...
```

**組織化の原則**:
- **[原則1]**: [説明]
- **[原則2]**: [説明]

## Naming Conventions

### ファイル名
- **[パターン1]**: [説明]（例: kebab-case.ts）
- **[パターン2]**: [説明]（例: PascalCase.tsx）

### ディレクトリ名
- **[パターン]**: [説明]

## Code Organization Principles

1. **単一責任**: [プロジェクト固有の適用方法]
2. **モジュール性**: [モジュール分割の基準]
3. **再利用性**: [共通コンポーネントの配置]

## Module Boundaries

[モジュール間の境界定義]

## File Size Guidelines

- **推奨サイズ**: [行数]
- **最大サイズ**: [行数]

## Documentation Standards

### プロジェクトレベル
- **README.md**: [役割]
- **[その他ドキュメント]**: [役割]

### コードレベル
- **コメント**: [コメント規約]
- **型定義**: [型定義の要求]
```

##### `specs/_steering/principles.md`

```markdown
# 開発原則

このドキュメントは、プロジェクト全体で共通して適用される開発原則を定義します。
すべてのPhase実装とタスク実行において、これらの原則に従ってください。

## TDD（Test-Driven Development）

### 基本サイクル: Red-Green-Refactor

1. **Red（失敗するテストを書く）**
   - 実装前に期待する動作を定義するテストを作成
   - テストが失敗することを確認（実装がまだないため）
   - テストは具体的で検証可能な振る舞いを記述

2. **Green（テストを通す最小限の実装）**
   - テストを通すための最小限のコードを実装
   - この段階では完璧を求めず、まず動作することを優先
   - すべてのテストが通ることを確認

3. **Refactor（コードを改善）**
   - テストが通る状態を維持しながらコードを改善
   - 重複の除去、命名の改善、構造の最適化
   - パフォーマンスやメンテナンス性の向上

### TDDの実践ルール

- **型定義だけを先に作ることは禁止**
  - 型定義は実装と共に作成し、実際の使用に基づいて定義する
  - 抽象的な型定義の事前作成は過剰設計につながる

- **テストファースト原則**
  - 常にテストから始める
  - テストなしでの実装追加は技術的負債となる

- **小さなステップで進める**
  - 一度に大きな変更をしない
  - 各サイクルは15分以内を目安

## SOLID原則

### Single Responsibility Principle（単一責任の原則）
- クラス・関数は単一の責任のみを持つ
- 変更理由は1つだけにする
- 例: ユーザー認証とデータベース操作を分離

### Open/Closed Principle（開放閉鎖の原則）
- 拡張に対して開いている
- 修正に対して閉じている
- 新機能追加時に既存コードを修正しない設計

### Liskov Substitution Principle（リスコフの置換原則）
- 派生クラスは基底クラスと置換可能
- 契約を破らない継承関係
- 例: 期待される振る舞いを維持した実装

### Interface Segregation Principle（インターフェース分離の原則）
- クライアントが使用しないメソッドへの依存を強制しない
- 大きな抽象より小さな特定の抽象
- **警告**: インターフェース（抽象）を作ることが目的化してはいけない

### Dependency Inversion Principle（依存性逆転の原則）
- 上位モジュールは下位モジュールに依存しない
- 両方とも抽象に依存する
- **警告**: 実装が1つしかない場合は抽象化は不要（YAGNI原則）

### SOLID原則の落とし穴

**過度な抽象化を避ける**:
- インターフェース（抽象）を作ることが目的になってはいけない
- 実装と乖離した抽象は技術的負債となる
- 実際に必要になってから抽象化する（YAGNI原則を参照）

## YAGNI原則（You Aren't Gonna Need It）

### 基本理念
- 実際に必要になるまで機能を追加しない
- 「将来使うかもしれない」という理由で実装しない
- シンプルさを保つことを最優先とする

### 適用例
- **過度な抽象化を避ける**: 実装が1つしかないのに抽象層を作らない
- **汎用化を避ける**: 現在の要件に必要な分だけ実装する
- **設定の外部化を避ける**: 変更の可能性が低いものはハードコードで十分
- **将来の拡張を予測しない**: 必要になったときにリファクタリング

### YAGNIの利点
- コードベースがシンプルに保たれる
- 開発速度が向上する
- 保守が容易になる
- 実際に使われないコードを書く無駄を削減

## TypeScript固有の原則

### 型の扱い
- `any`型の使用は絶対禁止
- `interface`より`type`を優先使用
  - `interface`は既存ライブラリの型拡張時のみ使用
  - 使用時は必ずコメントで理由を明記
- 型推論を活用し、必要最小限の型注釈

### インポート/エクスポート
- Barrel import/exportは禁止
- 各モジュールから直接インポート
- 循環参照を避ける設計

## コード品質基準

### 関数型プログラミングの活用
- 配列操作は`map`、`filter`、`reduce`を優先
- `push`などの破壊的操作は避ける
- イミュータブルなデータ構造を使用

### エラーハンドリング
- 例外は明示的にキャッチし適切に処理
- エラーの種類に応じた適切な対応
- ユーザーへの明確なエラーメッセージ

### セキュリティ
- SQLインジェクション対策
- XSS対策
- 認証・認可の適切な実装
- 機密情報の適切な管理

## アンチパターンと回避方法

### 過度な抽象化
- **問題**: 将来の要件を予測した過剰な設計
- **回避**: YAGNI（You Aren't Gonna Need It）原則の適用

### 神オブジェクト
- **問題**: 多くの責任を持つ巨大なクラス
- **回避**: 単一責任の原則に従った分割

### コピペプログラミング
- **問題**: 同じコードの重複
- **回避**: DRY（Don't Repeat Yourself）原則の適用

### マジックナンバー
- **問題**: ハードコードされた値
- **回避**: 定数として定義し意味を明確化

## 実装時の確認事項

各タスク実装時に以下を確認:
- [ ] TDDサイクルに従っているか
- [ ] SOLID原則に違反していないか
- [ ] 型安全性が保たれているか
- [ ] エラー処理が適切か
- [ ] セキュリティ上の問題はないか
- [ ] テストカバレッジは十分か
```

#### 2.4 完了報告

```markdown
✅ ステアリングドキュメントを作成しました
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📍 作成先: specs/_steering/

📝 作成されたファイル:
   - product.md (プロダクト方針)
   - tech.md (技術スタック)
   - structure.md (プロジェクト構造)
   - principles.md (開発原則)

💡 次のアクション:
   1. 各ドキュメントの内容を確認・編集してください
   2. プロジェクト固有の情報を追加してください
   3. `/sdd:init-task` でタスクを作成できます

⚠️ 重要:
   - 全ての /sdd:* コマンドは自動的にこれらのドキュメントを読み込みます
   - ステアリングドキュメントはプロジェクトの「永続的メモリ」として機能します
   - プロジェクトの方針や技術スタックが変更された場合は、このコマンドを再実行してください
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

### 3. Sync Mode（更新）

既存のステアリングドキュメントを最新の状態に更新：

#### 3.1 既存ドキュメントの読み込み

- `specs/_steering/product.md`
- `specs/_steering/tech.md`
- `specs/_steering/structure.md`
- `specs/_steering/principles.md`

#### 3.2 プロジェクトの変更検出

以下の変更を検出：

**技術スタック変更**:
- 新しい依存関係の追加
- 既存依存関係のバージョン更新
- フレームワークの変更

**プロジェクト構造変更**:
- 新しいディレクトリの追加
- ファイル命名パターンの変化
- モジュール構成の変更

#### 3.3 更新の提案

変更が検出された場合、AskUserQuestionツールで確認：

```
以下の変更が検出されました。ステアリングドキュメントを更新しますか？

変更内容:
1. tech.md: 新しい依存関係 "react-query" が追加されました
2. structure.md: 新しいディレクトリ "hooks/" が検出されました

選択肢:
- はい（推奨）: ステアリングドキュメントを更新
- いいえ: 現状を維持
- 個別に確認: 各変更を個別に確認
```

#### 3.4 ドキュメント更新

ユーザーの承認に基づいて該当ドキュメントを更新

#### 3.5 完了報告

```markdown
✅ ステアリングドキュメントを更新しました
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📍 更新先: specs/_steering/

📝 更新されたファイル:
   - tech.md (依存関係を更新)
   - structure.md (ディレクトリ構造を更新)

🔍 検出された変更:
   - 新しい依存関係: react-query, zustand
   - 新しいディレクトリ: hooks/, contexts/

💡 次のアクション:
   - 更新内容を確認してください
   - 必要に応じて手動で調整してください
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

## 注意事項

- **⚠️ 重要**: ステアリングドキュメントはプロジェクト全体の「唯一の真実の源」として機能します
- **⚠️ 重要**: 全ての `/sdd:*` コマンドは自動的にステアリングドキュメントを読み込みます
- 既存プロジェクトの場合、Bootstrap Modeで自動検出された内容を必ず確認・調整してください
- プロジェクトの方針や技術スタックが大きく変わった場合は、このコマンドを再実行してください
- ステアリングドキュメントは抽象的なレベルを保ち、具体的なコマンド名やファイル名は列挙しないでください

## 矛盾チェック（必須）

ステアリングドキュメント作成後、3つのドキュメント間の矛盾がないか必ず contradiction-checker SubAgent を使用して確認してください：

```bash
# contradiction-checker SubAgentを使用（指摘のみ、修正は行わない）
Task(contradiction-checker): specs/_steering/ の全ドキュメント間の矛盾をチェックしてください。product.md、tech.md、structure.md、principles.mdの整合性を確認してください。
```