503 lines
16 KiB
Markdown
503 lines
16 KiB
Markdown
---
|
||
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の整合性を確認してください。
|
||
```
|