peach-gen-feature-docs

peach-gen-feature-docs — 機能別仕様の生成

既存機能のコードに隠れている暗黙知（tacit knowledge）を構造化された仕様書に変換し、docs/기능별설명/{카테고리명}/{기능명}/ フォルダーにトピックごとの md ファイルとして文書化します。개요.md がインデックスの役割を果たし、AI は必要な文書だけを選んで読み込みます。 このスキルの主な成果物は、単なる文書の集合ではなく、後続の計画立案、実装、QA の段階で再注入する**as-is Context Pack（暗黙知→仕様書）**です。

トピックごとに分けるメリット — AI がコードだけを読むより、構造化された文書が効果的な理由：

• ファイル名が検索インデックスの役割を果たす → AI はファイル名だけを見て内容を推測できます
• 개요.md の文書インデックステーブルを使って、必要な文書だけを選んで読み込めます
• 複雑さに応じてファイル数を柔軟に調整できます（簡単な機能なら 3～4 ファイル、複雑な機能なら 8～12 ファイル）
• TDD ガイドにより、AI がテストまで自律的に完結できます

このスキルの位置付け（ワークフロー）

시나리오 B (기존 개선):
  /peach-gen-feature-docs → Context Pack 폴더를 컨텍스트로 주입 → AI가 개요 기반 자동 탐색 → /peach-gen-spec → 구현

시나리오 B (소규모):
  /peach-gen-feature-docs → Plan Mode → 직접 구현

신규 기능은 /peach-gen-spec 직접 사용 (이 스킬 불필요)

主な概念

• このスキルの本質は暗黙知→仕様書への変換です。コードに明示されていない設計根拠、ビジネス上の決定、履歴を構造化します。
• AI による自動分析＋開発者との対話型抽出の 2 段階で連携します。AI がコードや Git から抽出可能な情報を先に分析し、コードだけでは分からないことを開発者に質問します。
• この文書は既存機能の現状を構造化した保守用コンテキスト資産です。
• 後続のセッションでは docs/기능별설명/{카테고리명}/{기능명}/ フォルダー自体をコンテキストとして注入し、개요.md の文書インデックスを見て、作業に必要な文書だけを選んで読み込みます。
• 目的は「コードの代わりになる文書」を作ることではなく、変更範囲の把握、判断の背景の保持、テストの完結を迅速に行えるようにすることです。

使用する場面

• 既存機能の改善や修正の前に、コードの場所と内容を as-is 文書として記録するとき（主な用途）
• 新機能の実装完了後、再修正の可能性が高い重要機能を選んで文書化するとき
• ユーザーが「機能を文書化して」「機能別の仕様を作って」「/peach-gen-feature-docs」と依頼したとき

新機能の追加には、先に /peach-gen-spec を使用してください。このスキルは既存コードを分析できる場合に有効です。

入力

• カテゴリ名：上位分類フォルダー名（例：会員管理、掲示板、決済）
• 機能名（韓国語）：機能フォルダー名（例：ログイン、パスワード-変更）
• 一行の説明（任意）：개요.md の概要に使用

ワークフロー — 3 階層の暗黙知抽出パイプライン

第 1 段階：フォルダーの作成

docs/기능별설명/{카테고리명}/{기능명}/ — カテゴリフォルダーが存在しない場合は自動的に作成します

第 2 段階：第 1 階層 — AI による自動分析

AI がツールを使用し、コードと履歴から抽出可能な情報を自動的に分析します。

コードの静的分析

• モジュール構造、ファイル依存関係、パターンを把握します（Glob/Grep/Read）
• 暗黙知の調査チェックリストを確認します（以下のセクションを参照）

Git の考古学的調査

• 主要ファイルの変更頻度を確認します（git log --oneline {파일} | wc -l）
• co-change パターンを確認します — 同時に変更されるファイル＝暗黙的な結合（git log --format=format: --name-only | sort | uniq -c | sort -rn）
• 主な変更時点のコミットメッセージから設計根拠を抽出します（git log --all --oneline {파일}）

トピックごとの md ファイルの下書き作成（複雑さに応じてファイル数を柔軟に決定）— 以下のガイドに基づいて、AI が分析した内容を記入します

分割ルール：

• 1 つのファイルに 2 つ以上のトピックが含まれる場合 → 分割します
• ファイル名にトピックを含め、AI がファイル名だけで内容を推測できるようにします
• {기능명}-개요.md は必ず作成します（インデックスの役割）
• {기능명}-TDD-가이드.md は単独のファイルとして維持します（テストは独立した関心事です）

第 3 段階：第 2 階層 — 開発者との対話型抽出（CDM/ACTA に基づく）

AI が第 1 階層の分析で「コードだけでは分からない」と判断した項目について、開発者に質問します。 CDM プローブ質問セット（以下のセクション）を利用して AskUserQuestion で質問します。

• 質問は一度に 3～5 個ずつまとめ、効率的に進めます
• 開発者の回答を該当する文書のセクションに反映します
• 「分からない」または「該当なし」という回答も記録します（未確認事項として表示）

第 4 段階：第 3 階層 — 自己検証

AI が作成した文書を再確認します：

• 検証の問い：「この文書だけを読んで、機能を修正できるか？」
• 暗黙知の不足を特定した場合、開発者に追加で質問します
• 文書間の相互参照に整合性があるか確認します

第 5 段階：最終文書の確定＋後続段階の案内

• トピックごとの文書を最終保存します
• 後続の活用方法を案内します（gen-spec との連携、Plan Mode など）

暗黙知の調査チェックリスト

第 1 階層（AI による自動分析）で確認する項目です。発見した内容は文書に記録し、コードだけでは理由が分からない場合は第 2 階層で開発者に質問します。

コードレベル（ロジック文書向け）

• ハードコードされた定数／マジックナンバー → なぜその値なのか？
• 防御的なコード（try-catch、特定のエラーのみを処理する処理）→ 経験に基づくものか？
• コメント内の TODO/FIXME/HACK → 意図的な技術的負債か？
• 他モジュールの直接 import → 文書化されていない依存関係か？

データレベル（仕様書向け）

• 使用されていないカラム／状態値 → レガシーか、予約済みか？
• 複雑な JOIN／サブクエリ → 性能上の理由か、ビジネス上の理由か？

履歴レベル（Git の考古学的調査）

• 変更頻度の高いファイル → 複雑さやリスクが集中する箇所
• 同時に変更されるファイル（co-change）→ 暗黙的な結合関係

CDM プローブ質問セット

第 2 階層（開発者との対話型抽出）で AskUserQuestion を使って尋ねる質問テンプレート：

1. 「この機能で最も難しかった判断は何ですか？」
2. 「最初の設計から変わった部分があれば、なぜ変わったのですか？」
3. 「このコードを初めて見る開発者が見落としそうな落とし穴は何ですか？」
4. 「削除してはいけないコードや設定はありますか？その理由は何ですか？」
5. （動的な質問） AI が第 1 階層の分析で発見した特異点に基づいて作成します — 例：「[特異点] が変更された場合、どこに影響しますか？」

5 番目は固定の質問ではなく、AI が分析中に発見したことに基づいて動的に作成します。 開発者が「分からない」と答えた場合、その項目を文書に「未確認事項」として記録します。

ツールの使用

• Read/Glob/Grep：コードの静的分析、モジュール構造の把握
• Bash：Git の考古学的調査（git log、git blame など）
• AskUserQuestion：第 2 階層の開発者との対話型抽出
• Write：文書ファイルの作成

概要テンプレート（{기능명}-개요.md）

# {기능명} — 개요

## 1. 요약
{한 줄 설명}

## 2. 전체 흐름
(입력 → 검증 → 저장 등 단계 나열)

## 3. 관련 파일 (코드)
| 구분 | 경로 |
|------|------|
| Controller (Koa) | api/src/modules/... |
| Service | api/src/modules/... |
| DAO | api/src/modules/... |
| Type | api/src/modules/.../types.ts |
| Store (Pinia) | front/src/modules/.../store.ts |
| Component (Vue) | front/src/modules/.../*.vue |

## 4. 문서 인덱스
| 문서 | 핵심 내용 | 읽을 때 |
|------|----------|---------|
| [{기능명}-처리흐름-xxx.md] | 변환 N단계, 분기 조건 | 코드 수정 전 |
| [{기능명}-에러코드.md] | N개 에러코드 목록 | 에러 처리 추가 시 |
| [{기능명}-설계결정.md] | force_xxx 이유, yyy 배경 | 로직 변경 전 반드시 |
| [{기능명}-매핑-테이블명.md] | 필드 매핑 | 해당 테이블 수정 시 |
| ... | ... | ... |
| [{기능명}-TDD-가이드.md] | 테스트 N개, 실행법 | 테스트 실행 시 |

トピック別文書ガイド

トピック別の文書タイプと命名規則

タイプ	ファイル名のパターン	例
処理フロー	처리흐름-{함수/기능명}.md	처리흐름-execConvert.md
エラーコード	에러코드.md	-
設計判断	설계결정.md	ADR 形式を維持
データマッピング	매핑-{테이블명}.md	매핑-tang-order.md
解析ルール	파싱-{대상}.md	파싱-주문옵션.md
状態／コード	상태코드-매핑.md	-
入力データ	입력-{형식}.md	입력-JSON-샘플.md
TDD	TDD-가이드.md	常に単独のファイル

分割の判断基準

• 簡単な機能（3～4 ファイル）：概要＋ロジック＋仕様＋TDD（まとめても構いません）
• 複雑な機能（8～12 ファイル）：トピックごとに細分化します
• 基準：1 つのファイルが 100 行を超える場合は、分割を検討します

設計決定記録（ADR 形式）

設計決定.md または該当するトピックのドキュメントに含めます。コードだけでは分からない「なぜ」を記録します。

決定	コンテキスト（Context）	決定（Decision）	結果（Consequences）
例	PG 社の応答の平均は 2.8 秒	timeout を 3 秒に設定	断続的なタイムアウトが発生した場合は再試行が必要

AI がコードを修正するときは、既存の決定のコンテキストを理解する必要があります。そうしないと、ロジックを壊してしまう可能性があります。たとえば、「強制変換モード」が存在する理由を知らなければ、その分岐を削除したり変更したりすることがあります。

TDD-ガイドテンプレート（{機能名}-TDD-ガイド.md）

セクション構成：

1. テストファイル一覧
2. 実行コマンド（bunx vitest run {経路}）
3. サンプルデータの場所
4. Quick reference 表

既存の機能ドキュメントを読む（AI 向けの指針）

• 入口：まず {機能名}-概要.md を読みます
• ドキュメントのインデックステーブルで、「読むとき」列の内容を現在の作業と照らし合わせます
• 必要なドキュメントだけを選んで読み込みます
• フォルダー全体を読み込ませても、AI は概要を基点として自動で選択します

後続の活用に関する指針

• peach-agent-team、peach-agent-team-refactor：既存機能の修正が目的の場合、該当フォルダーを作業開始時のコンテキストとして事前に読み込みます
• gen-spec との連携時：Context Pack フォルダーをコンテキストとして読み込ませると、AI は概要を入口として必要なドキュメントを自動で選択します
• 手動での実装・分析：関連コード全体を再度確認する前に、ドキュメントフォルダーを先に読んで対象範囲を絞ります

規則

• パスはリポジトリのルートを基準にします（api/src/modules/、front/src/modules/ など）。
• カテゴリ名や機能名に空白がある場合は、ハイフンに置き換えます（例：パスワード変更 → パスワード-変更）。
• すべてのファイル名は {機能名}-{トピック}.md 形式にします（例：決済連携-概要.md、決済連携-TDD-ガイド.md）。
• {機能名}-概要.md は必ず作成します（入口＋インデックス）。
• {機能名}-TDD-ガイド.md は常に単独のファイルにします。
• 1 つのファイルに複数のトピックが含まれる場合は、分割します。
• カテゴリフォルダーの例：会員管理、掲示板、決済、商品、注文、精算