16 KiB
16 KiB
description
| 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 ディレクトリ作成
mkdir -p specs/_steering
2.3 ステアリングドキュメント生成
以下の3つのファイルを生成（収集した情報を反映）：
specs/_steering/product.md
# 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
# 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]:
- 理由: [理由]
- 代替案: [検討した代替案]
- トレードオフ: [トレードオフ]
##### `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
# 開発原則
このドキュメントは、プロジェクト全体で共通して適用される開発原則を定義します。
すべての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 完了報告
✅ ステアリングドキュメントを作成しました
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📍 作成先: 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.mdspecs/_steering/tech.mdspecs/_steering/structure.mdspecs/_steering/principles.md
3.2 プロジェクトの変更検出
以下の変更を検出：
技術スタック変更:
- 新しい依存関係の追加
- 既存依存関係のバージョン更新
- フレームワークの変更
プロジェクト構造変更:
- 新しいディレクトリの追加
- ファイル命名パターンの変化
- モジュール構成の変更
3.3 更新の提案
変更が検出された場合、AskUserQuestionツールで確認：
以下の変更が検出されました。ステアリングドキュメントを更新しますか？
変更内容:
1. tech.md: 新しい依存関係 "react-query" が追加されました
2. structure.md: 新しいディレクトリ "hooks/" が検出されました
選択肢:
- はい（推奨）: ステアリングドキュメントを更新
- いいえ: 現状を維持
- 個別に確認: 各変更を個別に確認
3.4 ドキュメント更新
ユーザーの承認に基づいて該当ドキュメントを更新
3.5 完了報告
✅ ステアリングドキュメントを更新しました
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📍 更新先: specs/_steering/
📝 更新されたファイル:
- tech.md (依存関係を更新)
- structure.md (ディレクトリ構造を更新)
🔍 検出された変更:
- 新しい依存関係: react-query, zustand
- 新しいディレクトリ: hooks/, contexts/
💡 次のアクション:
- 更新内容を確認してください
- 必要に応じて手動で調整してください
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
注意事項
- ⚠️ 重要: ステアリングドキュメントはプロジェクト全体の「唯一の真実の源」として機能します
- ⚠️ 重要: 全ての
/sdd:*コマンドは自動的にステアリングドキュメントを読み込みます - 既存プロジェクトの場合、Bootstrap Modeで自動検出された内容を必ず確認・調整してください
- プロジェクトの方針や技術スタックが大きく変わった場合は、このコマンドを再実行してください
- ステアリングドキュメントは抽象的なレベルを保ち、具体的なコマンド名やファイル名は列挙しないでください
矛盾チェック（必須）
ステアリングドキュメント作成後、3つのドキュメント間の矛盾がないか必ず contradiction-checker SubAgent を使用して確認してください：
# contradiction-checker SubAgentを使用（指摘のみ、修正は行わない）
Task(contradiction-checker): specs/_steering/ の全ドキュメント間の矛盾をチェックしてください。product.md、tech.md、structure.md、principles.mdの整合性を確認してください。