style-anchors-collection

スタイルアンカーコレクション

技術要件で承認されたパターンを示すコード例を体系的に特定、文書化、整理します。実装全体で使用するスタイルアンカーの構造化ライブラリを作成します。

前提条件

• technical-requirements.yaml が完成している
• 任意：既存のコードベースまたは参照リポジトリへのアクセス

目的

スタイルアンカーは、実装のテンプレートとなる具体的なコード例です。以下によって、実装のブレを防ぎます。

• コーディング開始前に承認済みのパターンを確立する
• 抽象的な説明ではなく、具体的なファイル名と行番号の参照を提示する
• 各パターンをいつ、どのように使うかを文書化する
• プロジェクトで再利用できるパターンライブラリを作成する

収集プロセス

ステップ 0：出力ディレクトリを決定する

パラメーターとしてディレクトリが指定されていない場合は、ユーザーに尋ねます。

「スタイルアンカーはどこに作成しますか？（要件ドキュメントと同じベースディレクトリを指定してください）」

ユーザーの回答を待ちます。指定されたパスを base_directory として保存します。

ステップ 1：技術的コンテキストを読み込む

1. {base_directory}/requirements/technical-requirements.yaml を読み込む

2. 主要なアーキテクチャパターンを解析する：

   • アーキテクチャパターン（モノリシック、マイクロサービスなど）
   • 技術スタック（言語、フレームワーク、ライブラリ）
   • テスト戦略（TDD、フレームワーク）
   • データモデルのアプローチ（データベース、スキーマパターン）
   • API パターン（REST、GraphQL など）
   • セキュリティパターン（認証、バリデーション）

3. アンカーを収集するパターンカテゴリを特定する（一般的なカテゴリ）：

   • サービス - 依存性注入を用いたサービスレイヤーパターン
   • テスト - テスト構成、モック、TDD パターン
   • バリデーション - 入出力のバリデーション、スキーマバリデーション
   • API - エンドポイントハンドラー、ミドルウェア、ルーティング
   • データアクセス - データベースクエリ、ORM パターン、マイグレーション
   • エラー処理 - エラーの種類、エラーの伝播、復旧

ステップ 2：収集計画を提示する

特定したカテゴリをユーザーに表示します。

## Style Anchors Collection

Based on your technical requirements, I'll collect code examples for these pattern categories:

1. Services (Effect.Service pattern with dependency injection)
2. Testing (Effect service testing with @effect/vitest)
3. Validation (Schema.Class validation patterns)
4. Error Handling (Tagged errors with Effect)

For each category, I'll ask you to provide:
- File path to exemplar code
- Line range (e.g., 10-50)
- What the pattern demonstrates
- When to use it

You can provide examples from:
- Your current codebase
- A reference repository (will link to it)
- Suggest "none" to skip a category

次のように尋ねます：「収集を開始してもよろしいですか？」

確認を待ちます。

ステップ 3：対話形式で収集する

特定した各カテゴリについて：

3.1. ソースファイルを尋ねる：

## Category: [Category Name]

What file demonstrates your preferred [pattern description]?

Options:
1. Provide file path from current project (e.g., src/services/UserService.ts)
2. Provide URL to reference repository file
3. Type "none" to skip this category
4. Type "help" for guidance on what makes a good style anchor

Your answer:

3.2. 行範囲を尋ねる：

What line range should I reference?

Format: Start-End (e.g., 10-50)
Or: Single line number (e.g., 25)
Or: "all" for entire file

Your answer:

3.3. ファイルにアクセスできる場合は、読み込んで表示する：

## Code Preview

[Display the code from specified lines]

Does this look correct? (yes/no/adjust)

「調整する」の場合は、行範囲を尋ねる手順に戻ります。

3.4. どのようなパターンを示しているか尋ねる：

What does this code example demonstrate?

Examples:
- "Service pattern with Effect.Service and dependency injection"
- "TDD test structure using it.effect from @effect/vitest"
- "Schema validation with proper error handling"

Your answer:

3.5. いつ使用するか尋ねる：

When should developers use this pattern?

Examples:
- "When creating any service class in the service layer"
- "When testing Effect-based services"
- "When validating external input data"

Your answer:

3.6. アンカー ID を生成する：

パターン名からアンカー ID を作成します（ケバブケース。例：service-pattern、test-effect-services）。

3.7. 確認して続行する：

✓ Collected anchor: [anchor-name]

Continue to next category? (yes/no/review)

ステップ 4：出力を生成する

4.1. ディレクトリ構造を作成する：

mkdir -p {base_directory}/artifacts/style-anchors

4.2. index.yaml を生成する：

以下を含む {base_directory}/artifacts/style-anchors/index.yaml を作成します。

• バージョンとメタデータ
• 収集したアンカーを含むカテゴリ
• ソース参照を含むアンカー定義
• パターンをタスクの種類に対応付ける使用マトリックス
• 合計数と収集日

4.3. 個別の .md ファイルを生成する：

収集した各アンカーについて、以下を含む {base_directory}/artifacts/style-anchors/[anchor-id].md を作成します。

• YAML フロントマター（id、name、category、tags、created date）
• 概要セクション
• ソース参照
• コード例（ファイルにアクセスできる場合）
• 実証する内容
• 使用するタイミング
• パターン要件（ベストプラクティスから導出）
• 避けるべきよくある間違い（ベストプラクティスから導出）
• 関連アンカー（相互参照）

4.4. パターン要件と間違いを記入する：

implementation-plan-best-practices の知識を使って、以下を追加します。

• ✓ パターン要件：そのパターンに固有の必須項目を 3～7 件
• ❌ よくある間違い：避けるべきアンチパターンを 3～7 件

ステップ 5：概要

収集の概要を表示します。

## Style Anchors Collection Complete ✓

**Directory:** {base_directory}/artifacts/style-anchors/

**Collected Anchors:** [count]

📁 Categories:
  - Services: [n] anchors
  - Testing: [n] anchors
  - Validation: [n] anchors
  - Error Handling: [n] anchors

📄 Generated Files:
  ✓ index.yaml (master index with usage matrix)
  ✓ [anchor-1].md
  ✓ [anchor-2].md
  ✓ [anchor-3].md

These anchors will be automatically referenced by implementation-planner
when generating task instructions.

Next Step: Run /implementation-planner to generate milestones and tasks

出力形式

index.yaml の構造

マスターインデックスファイルには、version、project、generated、technical_requirements_ref、categories（それぞれに id、name、description、anchors リストを含む）、anchors（それぞれに id、name、file、category、source reference、applies_to ルール、tags を含む）、usage_matrix（アーキテクチャパターンとタスクタイプを推奨アンカーに対応付けるもの）、meta（件数と日付）が含まれます。

個別の Anchor .md の構造

各アンカーファイルには、YAML フロントマター（id、name、category、tags、created）と、Overview、Source Reference、Code Example、What This Demonstrates、When to Use、Pattern Requirements、Common Mistakes to Avoid、Related Anchors、Test Coverage の各セクションが含まれます。

index.yaml と個別のアンカーファイルの完全な仕様（すべてのフィールド、書式ルール、使用マトリックスの構造を含む）については、references/output-spec.md を参照してください。

アンカードキュメントの完全な例については、references/example.md を参照してください。

パターン要件と間違いの生成

サービスパターンの場合：

要件：

• ✓ すべてのサービスメソッドは Effect 型を返す必要があります
• ✓ 非同期操作には Effect.gen を使用します
• ✓ エラーはスローせず、タグ付きエラーで失敗させます
• ✓ 処理の前に Schema.decode で入力を検証します
• ✓ すべての依存関係を dependencies 配列で宣言します

間違い：

• ❌ Effect.gen の代わりに async/await を使用する
• ❌ Effect.fail の代わりにエラーをスローする
• ❌ 依存性注入を使わずにデータベースへ直接アクセスする
• ❌ 入力検証を省略する
• ❌ 外部データに any や型アサーションを使用する

テストパターンの場合：

要件：

• ✓ Effect のテストには @effect/vitest の it.effect を使用します
• ✓ テストのセットアップですべてのサービス依存関係を提供します
• ✓ 成功ケースと失敗ケースの両方をテストします
• ✓ 動作を説明する具体的なテスト名を付けます
• ✓ TDD に従い、先にテストを書いてから実装します

間違い：

• ❌ Effect ベースのコードに通常の it() を使用する
• ❌ 必要なサービス依存関係を提供しない
• ❌ ハッピーパスだけをテストし、エラーを無視する
• ❌ 「test 1」や「it works」のような曖昧なテスト名を付ける
• ❌ 壊れた実装に合わせるためにテストを変更する

検証パターンの場合：

要件：

• ✓ すべてのデータ検証に Schema.Class を使用します
• ✓ システムの境界（ユーザー入力、外部 API）で検証します
• ✓ 検証エラーを返し、スローしません
• ✓ 役に立つエラーメッセージを含めます
• ✓ 外部データに型アサーションを決して使用しません

間違い：

• ❌ 検証の代わりに型アサーションを使用する
• ❌ 検証エラーの代わりに一般的なエラーをスローする
• ❌ 内部関数の引数を検証する（内部コードを信頼する）
• ❌ 外部入力の検証を省略する
• ❌ 外部データに any 型を使用する

エラー処理パターンの場合：

要件：

• ✓ タグ付きエラーを使用します（カスタムエラークラスを伴う Effect.fail）
• ✓ エラーオブジェクトにコンテキスト（ID、値）を含めます
• ✓ エラーを Effect で伝播させ、捕捉して隠しません
• ✓ エラー型は使用箇所の近くで定義します
• ✓ 関数シグネチャに想定されるエラーを記載します

間違い：

• ❌ Effect.fail の代わりにエラーをスローする
• ❌ 型付きエラーの代わりに文字列のエラーメッセージを使用する
• ❌ エラーを捕捉して無視する
• ❌ コンテキストのない一般的なエラーメッセージを使う
• ❌ 関数が生成する可能性のあるエラーを記載しない

使用マトリックスの生成

技術要件をアンカーの推奨項目に対応付けます。

architecture.pattern に基づく場合：

• effect-based-services → service-pattern、test-pattern、error-handling
• schema-validation → validation-schema、api-validation
• rest-api → api-pattern、validation-schema、error-handling

タスクタイプに基づく場合：

• code → レイヤーに対応する主なパターン + validation + error-handling
• test → test-pattern + テスト対象のパターン
• api → api-pattern + validation-schema + error-handling
• docs → （通常、アンカーは不要）
• config → （通常、アンカーは不要）

ベストプラクティス

優れたスタイルアンカーの条件

1. 具体的 - 抽象的な説明ではなく、実際のファイルパスがある
2. 明確 - 精度を高める行番号がある（20～50行が理想）
3. 完全 - スニペットだけでなく、パターン全体が示されている
4. 最新 - 現在のベストプラクティスを反映している
5. 模範的 - パターンが正しく実装されている

注意すべき点（収集時）

• コード例に TODO や FIXME がある
• ファイルで非推奨のパターンが使われている
• コードをコンパイルまたは実行できない
• 例が単純すぎる（10行未満）
• 例が複雑すぎる（100行超）
• パターンに対するテストが存在しない

エッジケース

既存のコードベースがない場合

ユーザーに現在のコードベースがない場合：

I notice you don't have an existing codebase. Would you like to:

1. Skip style anchor collection for now (can add later)
2. Reference external examples (Effect documentation, framework examples)
3. Create minimal example files as anchors

Which approach works best for your project?

ユーザーがすべてのカテゴリーをスキップする場合

No style anchors collected. This means:

⚠️  Implementation-planner will generate tasks WITHOUT concrete examples
⚠️  Risk of architectural drift increases
⚠️  Developers will need to infer patterns from requirements

Recommendation: Collect at least 1-2 anchors for critical patterns
(e.g., service pattern, test pattern)

Continue without anchors? (yes/no)

ファイルにアクセスできない場合

ユーザーが読み取りできないファイルパスを指定した場合：

I can't access [file-path]. Would you like to:

1. Provide a different file path
2. Paste the code directly (I'll store it in the anchor)
3. Provide a URL to the file
4. Skip this anchor

Your choice:

実装プランナーとの連携

implementation-planner の実行時：

1. スタイルアンカーを読み込む：

   Read {base_directory}/artifacts/style-anchors/index.yaml
   

2. 生成された各タスクについて：

   • タスクの種類とファイルのパターンを判定する
   • usage_matrix を照会して、推奨されるアンカーを確認する
   • applies_to ルールに基づいてアンカーを絞り込む
   • 関連性の高い上位 2～3 件のアンカーをタスクの指示に含める

3. タスク指示のテンプレート：

   instructions: |
     ## Style Anchors
     Follow these patterns:
     - `[anchor-id]` ([file]) - [what it demonstrates]
     - `[anchor-id]` ([file]) - [what it demonstrates]
   
     See artifacts/style-anchors/[anchor-id].md for detailed examples.
   
     ## [rest of task instructions]
   

検証

生成後、次の項目を検証します：

• index.yaml が有効な YAML である
• すべてのアンカー ID が一意である
• すべてのカテゴリー参照が解決される
• インデックス内のアンカーに対応するすべての .md ファイルが存在する
• すべての .md ファイルの frontmatter が index.yaml と一致する
• ソースの行範囲が有効な形式である
• 使用マトリックスが有効なアンカーを参照している
• 各カテゴリーに少なくとも 1 つのアンカーがある

使用方法

スタイルアンカーを収集するには：

/style-anchors-collection [base-directory]

ディレクトリが指定されていない場合は、現在のディレクトリに requirements/technical-requirements.yaml があるか確認し、自動検出します。

見つからない場合は、ユーザーに「要件ドキュメントはどこにありますか？」と尋ねます。

続行する前に、ユーザーがパスを指定するまで待ちます。これを base_directory として保存します。

このスキルは次の処理を行います：

1. {base_directory}/requirements/technical-requirements.yaml から技術要件を読み込む
2. 収集するパターンカテゴリーを特定する
3. 各カテゴリーのアンカーを対話的に収集する
4. {base_directory}/artifacts/style-anchors/ に index.yaml を生成する
5. 各アンカーの個別の .md ファイルを生成する
6. 収集の概要を表示する

例

アンカードキュメントのサンプルは、references/example.md を参照してください。