wiki-from-code

コードからWikiを作成

現在の製品の動作に関するWikiです。各機能を1ページずつ取り上げ、その動作と、コードとリポジトリ内の他の記述との食い違いを一覧にします。

出力フォルダー：

• デフォルト：wiki/（リポジトリのルート）
• またはスキルの呼び出し時、もしくはユーザーが指定したフォルダー
• すべてのパスは出力フォルダー内の相対パスです
• features-catalog/ ディレクトリがある場合 → features/.catalog/ に移動します

食い違いとは、コードと、それについての記述（コメント、docstring、開発者向けドキュメント、API 仕様、設定、インフラ、テスト）との不一致です。異なっている場合、実装されていない場合、使用されていない場合などがあります。

モード

モード	条件
build	features/ またはルートの README.md にベースラインがない、Git がない、またはユーザーが再構築を依頼した場合
update	features/ とベースラインが存在する場合：ベースライン以降にコードで変更された内容のみを更新します

手順

- [ ] 1. Catalog
- [ ] 2. Indexes
- [ ] 3. Feature pages (one subagent per area)
- [ ] 4. Merge
- [ ] 5. Validate
- [ ] 6. Report

ファイルを書き込む前に、references/behaviors.md と references/layout.md を読みます。

ルール

• 情報源はリポジトリのみです。
• 現在のコードを優先します（コメント、docstring、開発者向けドキュメント、API 仕様、設定、テストなどの記述より優先）。コードに存在しないことや、コードと異なることを記述している場合は、mismatches/ にのみ記載し、機能ページに「こうあるべき」として記載してはいけません。
• リポジトリに存在するパスのみを記述します。推測したり、パスを作成したりしてはいけません。
• 領域と機能の名称は、コード、技術スタック、ファイル、クラスなどではなく、製品およびユーザーの視点から付けます。
• ドメイン用語（ドキュメントにある用語を優先）を使い、Wiki 全体で概念ごとに用語を統一します。
• 機能についての情報が増えるにつれて、カタログのファイル名と内容を更新します。
• 機能はコード上の「アクション」だけでなく、エンドツーエンドのフローまたはユースケースとして扱い、説明します。

1. カタログ

リポジトリに対して catalog-features スキルを実行し、同じモードで、出力フォルダーを features/.catalog/ にします。

update の場合：ベースラインのコミットを取得 > git diff --name-status -M {baseline}..HEAD > 更新または削除されたファイルを適宜処理します。

2. インデックス

機能ページを作成する前に、features/ のインデックスを作成します。

layout.md

3. 機能ページ

領域ごとにサブエージェントを1つ割り当て、並行して作業します（update の場合は影響を受ける領域のみ）。各サブエージェントには、領域、その下位領域とカタログ機能（機能 YAML）、許可されたコードパス、features/.catalog/README.md の Domain、上記のルール、references/behaviors.md、references/layout.md を渡します。update の場合は、領域の既存ページと食い違い、変更された機能も渡します。

サブエージェントは、各機能について、カタログのリンクを起点に次の作業を行います。

1. カタログ機能 YAML で、実装ファイルを code に追加し、tests を追加します。
2. 機能ページ（layout.md › 機能ページ）を作成します：説明、続いて動作（behaviors.md）。
3. 食い違いごとに1件を返します。食い違いの種類と、食い違いページの各セクションをすべて含めます（layout.md › 食い違い）。

サブエージェントは、features/ および features/.catalog/ の自身の領域内にのみ書き込みます。カタログ機能に欠落、誤った名前、誤った配置がある場合は、領域のカタログファイルで修正します。領域外のもの（食い違いページ、カタログの README、他の領域など）は返します。

サブエージェントは、追加、変更、削除したファイル、食い違い（update の場合は解消したものも）、自身の領域外での変更、未解決の質問、カタログの誤り、Domain に不足している用語を返します。

4. マージ

1. 名前変更または移動したページへのリンクも含め、担当範囲外でサブエージェントが返した変更を適用します。Domain にない用語は、features/.catalog/README.md の Domain に追加します。
2. features/ 内のすべての README.md を更新し、現在存在する機能ページを一覧にします。ルートの README.md を作成し、各フォルダー（.catalog/ を除く）のリンクと目的に加え、ベースラインコミットを記載します。
3. サブエージェントが返した不一致ページを作成します。複数の領域から同じ不一致が報告された場合は、不一致ページを1つにまとめます。
4. 1つの概念に2つの用語がある場合は、1つに統一し、もう一方を使用しているページを修正します。
5. update：解決済みの不一致を削除します。
6. mismatches/README.md に不一致の一覧を記載します（layout.md › Mismatches）。

5. 検証

Structure
- [ ] README.md is a sitemap with the baseline commit
- [ ] Every catalog feature has a feature page, and its feature YAML lists the rest of its implementation files in `code` and its tests in `tests`; `features/` mirrors the catalog's areas and subareas
- [ ] Every `links`, `code`, and `tests` path exists in the repo

Content
- [ ] Every feature page has a Description and at least one behavior under Behaviors; every behavior passes the check in [references/behaviors.md](references/behaviors.md)
- [ ] Every disagreement between code and claims has a mismatch page
- [ ] update: resolved mismatches removed; nothing left for deleted code

6. 報告

着手する場所。結果（update：追加、変更、削除した機能）。ユーザーへの影響が大きい順に、不一致の種類。カタログのエラー。未解決の質問。

次のアクション

• イシュー、要件、ユーザードキュメントと比較 → detect-product-mismatches
• QA 用語で機能を説明 → qa-explain-behavior
• 機能のテストケース → qa-write-test-cases