yodogawa 2.0.0 → 2.1.0

package/skills/c-002-update-documentation/examples/project-doc-updates.md

@@ -0,0 +1,190 @@
+# プロジェクトドキュメント更新の記載例
+
+SKILL.md 手順4で使うテンプレート。要件・ドメイン・設計・README など各ドキュメントに追記するサンプル。
+
+## features-implemented.md
+
+```markdown
+## ユーザー認証・認可
+
+### メール認証機能（新規追加）
+
+**概要**: ユーザー登録時にメールアドレスを検証する機能
+
+**実装内容**:
+- ユーザー登録時にメール認証トークンを生成し、メールを送信
+- ユーザーがメール内のリンクをクリックすると、メールアドレスが検証される
+- 検証済みユーザーのみが特定の機能にアクセスできる
+
+**主要な機能**:
+- メール認証トークン生成（UUID v4、有効期限 24 時間）
+- メール送信（SendGrid 経由）
+- メール検証エンドポイント（`POST /api/auth/verify-email`）
+- 検証済みフラグ管理（`email_verified` カラム）
+
+**関連タスク**: task000001-email-verification
+**実装日**: 2024-01-15
+**PR/MR**: #123
+```
+
+## features-planned.md
+
+- 実装完了した機能をリストから削除
+- または、ステータスを「実装済み」に変更し `02-features-implemented.md` への参照を追加
+
+## domain-model.md
+
+```markdown
+## User（ユーザー）
+
+**概要**: システムのユーザーアカウント
+
+**属性**:
+- id: ユーザーID（UUID）
+- email: メールアドレス（必須、一意）
+- password_hash: パスワードハッシュ（必須）
+- email_verified: メール検証済みフラグ（新規追加）
+- email_verification_token: メール検証トークン（新規追加）
+- email_verification_expires_at: トークン有効期限（新規追加）
+
+**振る舞い**:
+- register(): ユーザー登録
+- sendVerificationEmail(): 検証メール送信（新規追加）
+- verifyEmail(token): メール検証（新規追加）
+- login() / logout()
+
+**制約**:
+- メールアドレスは一意
+- 検証トークンは24時間で期限切れ（新規追加）
+- パスワードは最低8文字
+```
+
+## ubiquitous-language.md
+
+```markdown
+## メール検証（Email Verification）
+
+**定義**: ユーザーが登録したメールアドレスが有効であることを確認するプロセス
+**コンテキスト**: ユーザー認証・認可
+**関連用語**: メール検証トークン、検証済みフラグ
+
+## メール検証トークン（Email Verification Token）
+
+**定義**: メールアドレスの所有権を確認するための一時的なトークン
+**技術的詳細**: UUID v4、有効期限 24 時間、一度使用したら無効化
+```
+
+## data-model.md
+
+```markdown
+## users テーブル
+
+| カラム名 | データ型 | NULL | デフォルト値 | 説明 | 追加日 |
+|---------|---------|------|------------|------|--------|
+| id | UUID | NOT NULL | gen_random_uuid() | ユーザーID | 2024-01-10 |
+| email | VARCHAR(255) | NOT NULL | - | メールアドレス（一意） | 2024-01-10 |
+| password_hash | VARCHAR(255) | NOT NULL | - | パスワードハッシュ | 2024-01-10 |
+| email_verified | BOOLEAN | NOT NULL | false | メール検証済みフラグ | 2024-01-15（新規） |
+| email_verification_token | UUID | NULL | - | 検証トークン | 2024-01-15（新規） |
+| email_verification_expires_at | TIMESTAMP | NULL | - | トークン有効期限 | 2024-01-15（新規） |
+
+**インデックス**:
+- PRIMARY KEY: id
+- UNIQUE: email
+- INDEX: email_verification_token（新規追加）
+```
+
+## api-spec.md
+
+```markdown
+## POST /api/auth/verify-email
+
+**概要**: メール検証トークンを使用してメールアドレスを検証する
+**認証**: 不要
+
+**リクエスト**:
+{
+  "token": "550e8400-e29b-41d4-a716-446655440000"
+}
+
+**レスポンス（成功）**:
+{
+  "message": "Email verified successfully",
+  "userId": "123e4567-e89b-12d3-a456-426614174000"
+}
+
+**レスポンス（エラー）**:
+- 400 Bad Request: トークンが無効または期限切れ
+- 404 Not Found: ユーザーが見つからない
+```
+
+## screen-design.md
+
+```markdown
+## メール検証完了画面
+
+**パス**: `/verify-email?token={token}`
+
+**UI コンポーネント**:
+- ヘッダー（アプリ名、ロゴ）
+- メッセージエリア（成功/失敗時のメッセージ）
+- アクションボタン（ログイン / 検証メール再送信）
+
+**画面遷移**:
+- 成功時: ログイン画面（/login）へ
+- 失敗時: 検証メール再送信画面へ
+
+**実装ファイル**: `src/pages/VerifyEmail.tsx`
+```
+
+## README.md
+
+```markdown
+## 環境変数設定
+
+`.env.example` をコピーして `.env` ファイルを作成:
+
+- `DATABASE_URL`: データベース接続URL
+- `JWT_SECRET`: JWT トークンの秘密鍵
+- `SENDGRID_API_KEY`: SendGrid API キー（新規追加）
+- `SENDGRID_FROM_EMAIL`: 送信元メールアドレス（新規追加）
+
+## 主な機能
+
+- ユーザー登録・ログイン
+- **メール認証（新規追加）**
+- パスワードリセット
+- プロフィール管理
+```
+
+## CHANGELOG.md
+
+```markdown
+## [Unreleased]
+
+### Added
+- メール認証機能を実装（task000001-email-verification）
+  - メール検証用エンドポイント（`POST /api/auth/verify-email`）
+  - メール検証トークン管理（有効期限 24 時間）
+  - SendGrid 統合によるメール送信
+
+### Changed
+- User テーブルに `email_verified`, `email_verification_token`, `email_verification_expires_at` カラムを追加
+```
+
+## .env.example
+
+```bash
+# データベース
+DATABASE_URL=postgresql://user:password@localhost:5432/myapp
+
+# JWT
+JWT_SECRET=your-jwt-secret-key
+
+# メール送信（新規追加）
+SENDGRID_API_KEY=your-sendgrid-api-key
+SENDGRID_FROM_EMAIL=noreply@example.com
+
+# アプリケーション
+APP_URL=http://localhost:3000
+```

package/skills/c-002-update-documentation/examples/task-doc-updates.md

@@ -0,0 +1,102 @@
+# タスクドキュメント更新の記載例
+
+SKILL.md 手順3で使うテンプレート。a-definition.md / b-research.md / c-implementation.md に追記する実装時の情報サンプル。
+
+## a-definition.md
+
+### 実装時の技術的決定
+
+```markdown
+## 実装時の技術的決定
+
+- **決定**: TypeORM から Prisma に変更
+- **理由**: マイグレーション管理が容易、型安全性が高い
+- **影響**: データアクセス層のコード変更、マイグレーションファイルの再作成
+
+- **決定**: JWT トークンの有効期限を 24h から 1h に変更
+- **理由**: セキュリティ向上
+- **影響**: リフレッシュトークン機能の追加実装
+```
+
+### 実装結果
+
+```markdown
+## 実装結果
+
+- **実装日**: 2024-01-15
+- **実装者**: {名前}
+- **ブランチ**: task/task000001-email-verification
+- **PR/MR**: #123
+- **テスト結果**:
+  - ユニットテスト: 100% 通過 (カバレッジ 85%)
+  - 統合テスト: 100% 通過
+  - E2E テスト: 100% 通過
+- **デプロイ**: staging 環境にデプロイ済み
+```
+
+## b-research.md
+
+### 実装時に発見したベストプラクティス
+
+```markdown
+## 実装時に発見したベストプラクティス
+
+- **Email 検証**: SendGrid の Webhook を使用して配信状態を追跡
+- **トークン管理**: Redis にトークンを保存し、自動期限切れを利用
+- **エラーハンドリング**: Zod を使用してバリデーションエラーを統一
+```
+
+### 技術的リスクの結果
+
+```markdown
+## 技術的リスクの結果
+
+- **リスク**: Email 送信の遅延
+  - **結果**: SendGrid の非同期処理で解決、平均送信時間 2 秒
+  - **軽減策**: ジョブキューによる非同期処理を実装
+
+- **リスク**: トークンの衝突
+  - **結果**: UUID v4 使用により衝突なし
+  - **軽減策**: 不要
+```
+
+## c-implementation.md
+
+### 実装メモの追記
+
+```markdown
+- [x] **ステップ 1:** データベーススキーマの定義
+  - **成果物:** `migrations/001_create_users_table.sql`
+  - **詳細:** User テーブルに `email_verified`, `email_verification_token`, `email_verification_expires_at` カラムを追加
+  - **実装メモ**:
+    - Prisma migrate を使用
+    - 既存ユーザーには email_verified = false をデフォルト設定
+    - インデックスを email_verification_token に追加（検索高速化）
+```
+
+### 実装時間の記録
+
+```markdown
+## フェーズ 1: データモデルと API の実装
+
+**実装時間**: 4 時間（見積もり: 3 時間）
+```
+
+### 振り返りセクション
+
+```markdown
+## 振り返り
+
+### うまくいったこと
+- Prisma の型安全性により、コンパイル時にエラーを検出できた
+- TDD アプローチで品質を担保できた
+- ステップを小さく分けたことで、進捗管理が容易だった
+
+### 改善すべきこと
+- Email 送信のテストが複雑だった（モックの設定に時間がかかった）
+- トークン生成ロジックの設計に予想以上に時間がかかった
+
+### 次のタスクへのフィードバック
+- Email 送信のモックユーティリティを共通化する
+- トークン生成ロジックを再利用可能なライブラリとして抽出する
+```

package/skills/c-002-update-documentation/reference/doc-structure-and-checks.md

@@ -0,0 +1,100 @@
+# ドキュメント構造と整合性チェック
+
+SKILL.md 手順5（整合性検証）とベストプラクティスで参照する詳細資料。
+
+## ドキュメント整合性の検証項目
+
+### クロスリファレンスの確認
+
+- [ ] **要件 ↔ ドメインモデル**: features-implemented.md の機能が domain-model.md に反映されているか
+- [ ] **ドメインモデル ↔ データモデル**: domain-model.md のエンティティが data-model.md のテーブルに対応しているか
+- [ ] **ドメインモデル ↔ API 仕様**: domain-model.md の振る舞いが api-spec.md のエンドポイントに対応しているか
+- [ ] **API 仕様 ↔ 実装**: api-spec.md のエンドポイントが実際に実装されているか
+- [ ] **データモデル ↔ 実装**: data-model.md のテーブル定義がマイグレーションファイルと一致しているか
+
+### 用語の一貫性確認
+
+- [ ] ドキュメント全体で同じ用語を使用しているか
+- [ ] ubiquitous-language.md に記載された用語が各ドキュメントで使用されているか
+- [ ] コード内のクラス名・変数名がドメイン用語と一致しているか
+
+### リンク切れの確認
+
+- [ ] 内部リンクが正しいパスを指しているか
+- [ ] 参照先のドキュメント・セクションが存在するか
+
+## ドキュメント品質のレビュー観点
+
+- [ ] **正確性**: 実装内容と一致しているか
+- [ ] **完全性**: すべての変更が記載されているか
+- [ ] **明確性**: 第三者が理解できる内容か
+- [ ] **一貫性**: ドキュメント間で用語・形式が統一されているか
+- [ ] **最新性**: 古い情報が削除されているか
+
+## ベストプラクティス
+
+- **実装直後に更新**: 記憶が新しいうちに記録する
+- **差異を記録**: 計画と実装の差異は必ず記録し、次のタスクへのフィードバックとする
+- **スクリーンショット活用**: UI 変更の場合、スクリーンショットを添付して視覚的に記録
+- **リンクを活用**: ドキュメント間でリンクを張り、関連情報にすぐアクセスできるようにする
+- **バージョン管理**: ドキュメントもコードと同様に Git で管理
+- **段階的更新**: 大規模な更新は段階的に行い、一度に全てを更新しない
+- **レビューを受ける**: 重要な更新はチームレビューで正確性を担保
+- **テンプレート活用**: 繰り返し更新するドキュメントはテンプレート化
+- **自動化**: 可能な部分は自動化（API ドキュメント生成、データモデル図生成など）
+- **定期的な棚卸し**: ドキュメント全体を定期的にレビューし古い情報を削除
+
+## ドキュメント構造の参考
+
+### タスクレベル（`docs/tasks/task{id}-{スラッグ}/`）
+
+- `a-definition.md`: タスク定義（目的、ユーザーストーリー、受け入れ基準）
+- `b-research.md`: リサーチ（ベストプラクティス、技術選定）
+- `c-implementation.md`: 実装タスクリスト（フェーズ、ステップ）
+
+### プロジェクトレベル（`docs/`）
+
+- `01-requirements/`: 要件定義
+  - `02-features-implemented.md`: 実装済み機能
+  - `03-features-planned.md`: 計画中機能
+  - `05-user-stories.md`: ユーザーストーリー
+- `03-domain/`: ドメイン
+  - `01-domain-model.md`: ドメインモデル
+  - `02-ubiquitous-language.md`: ユビキタス言語
+- `04-design/`: 設計
+  - `03-screen-design.md`: 画面設計
+  - `04-data-model.md`: データモデル
+  - `05-api-spec.md`: API 仕様
+  - `06-architecture.md`: アーキテクチャ
+
+### その他
+
+- `README.md`: プロジェクト概要、セットアップ手順
+- `CHANGELOG.md`: 変更履歴
+- `.env.example`: 環境変数テンプレート
+
+## 自動化のヒント
+
+将来的に、以下のスクリプトでドキュメント更新を一部自動化することを検討：
+
+- `scripts/update-docs.sh`: コミットログから変更内容を抽出してドラフトを作成
+- `scripts/generate-api-docs.sh`: コードから API 仕様書を生成
+
+## コミットメッセージのテンプレート
+
+```
+docs(task-{task-id}): update documentation for {機能名}
+
+Task-level documentation:
+- Update a-definition.md with implementation results
+- Update b-research.md with discovered best practices
+- Update c-implementation.md with implementation notes and retrospective
+
+Project-level documentation:
+- Add {機能名} to features-implemented.md
+- Update domain-model.md / data-model.md / api-spec.md
+- Update README.md with setup instructions
+- Add changelog entry
+
+Related: task{task-id}-{スラッグ}
+```

package/templates/tasks/task-template/a-definition.md

@@ -3,7 +3,7 @@
 <!--
 このドキュメントについて:
   - 格納場所: docs/tasks/task000001-{スラッグ}/a-definition.md
-  - 作成方法: /b-001-CreateTaskDefinition ワークフローで作成
+  - 作成方法: /b-001-CreateTaskDefinition スキルで作成
   - 関連ドキュメント:
     - b-research.md (リサーチドキュメント)
     - c-implementation.md (実装タスクリスト)

package/templates/tasks/task-template/b-research.md

@@ -3,7 +3,7 @@
 <!--
 このドキュメントについて:
   - 格納場所: docs/tasks/task000001-{スラッグ}/b-research.md
-  - 作成方法: /b-002-CreateTaskResearch ワークフローで作成
+  - 作成方法: /b-002-CreateTaskResearch スキルで作成
   - 前提条件: a-definition.md が作成済みであること
   - 関連ドキュメント:
     - a-definition.md (タスク定義ドキュメント)

package/templates/tasks/task-template/c-implementation.md

@@ -3,8 +3,8 @@
 <!--
 このドキュメントについて:
   - 格納場所: docs/tasks/task000001-{スラッグ}/c-implementation.md
-  - 作成方法: /b-003-CreateTaskImplementation ワークフローで作成
-  - 実行方法: /c-001-ImplementTask ワークフローで各ステップを実行
+  - 作成方法: /b-003-CreateTaskImplementation スキルで作成
+  - 実行方法: /c-001-ImplementTask スキルで各ステップを実行
   - 前提条件: a-definition.md と b-research.md が作成済みであること
   - 関連ドキュメント:
     - a-definition.md (タスク定義ドキュメント)