incu-way-docs

コードベースのドキュメント作成プロセス

既存のコードベースを、アプリケーションの概要、構築方法、各要素の関係、そしてユーザー向けの動作を備えた製品の場合は機能面での動作を明確かつ追跡可能なドキュメントにまとめるための、ゲート駆動型ワークフローです。成果物は docs/architecture/（必要に応じて機能やドメインに関するドキュメントも）に保存され、他の incu-way フローが Phase 0 で参照するコンテキストになります。

呼び出し方法は2つあります。

• incu-way-init の一部として実行する場合（ブラウンフィールドのオンボーディング）： 現在の init ブランチ／ワークツリーに書き込みます。ドキュメントは init PR に含まれます。別のブランチや PR は作成しません。
• 単独で実行する場合（更新またはモジュールのドキュメント作成）： 専用ブランチ docs/{slug} を作成し、develop に PR を送ります。

これはドキュメント作成フローです。incu-way-init と同様に、.ways/state.json は管理しません（このモデルは feature／bug／security の作業用です）。

---

リポジトリの適格性チェック（最初に実施）

Phase 0 の前に、現在のリポジトリが ~/.ways/config.yaml の blacklist（形式は incu-base の global-config ルールに準拠し、常時適用）に一致するか確認します。一致する場合は、このリポジトリが incu-way のブラックリストに登録されていることをユーザーに伝え、例外的に続行するか中止するかを尋ねます。回答があるまで、どのフェーズも実行しないでください。ファイルが存在しない場合、または一致しない場合は、通常どおり続行します。

---

Phase 0 — 調査と受け入れ

目標： 何をドキュメント化するか決める前に、既存の内容を把握します。読み取り専用です。

受け入れ

1. 利用できるコンテキストに基づき、対象範囲を確認します。
   • リポジトリ全体、または特定のモジュール／サービス／境界づけられたコンテキスト
   • 詳細度：アーキテクチャのみ、またはアーキテクチャ＋機能／ドメイン
   • 新規作成か、既存ドキュメントの更新か
2. 既存のドキュメント（README.md、docs/、PRD.md、Wiki のエクスポートなど）を読み、重複を避けるとともに、内容が現状と乖離している箇所を特定します。

コードベースのインベントリ作成

調査のみを行い、まだ書き込みはしません。

• 言語／フレームワーク／ランタイム — マニフェストと設定から確認します。
• エントリーポイント — main、サーバーの起動処理、CLI、ハンドラー、スケジュールされたジョブ。
• モジュール／レイヤー — 実際のトップレベルの構成（ヘキサゴナル、MVC、機能別フォルダー、マイクロサービスなど）。
• データストア — DB、キャッシュ、キュー、ブロブストレージ。スキーマ／マイグレーションの場所。
• 外部連携 — サードパーティ API、決済／認証プロバイダー、呼び出し先または呼び出し元となる内部サービス。
• ビルド／実行／テスト／デプロイ — スクリプト、CI 設定、コンテナ化、インフラストラクチャ・アズ・コード。
• 横断的関心事 — 認証、設定、ロギング／可観測性、エラー処理。

Phase 0 の終了条件

Gate 1 の前に、Claude が次の内容を説明できる状態にします。

• ドキュメント化する対象範囲と詳細度
• 主なモジュール／サービスと、それらの関係がどのように見えるか
• 使用されているデータストアと外部連携
• 既存ドキュメントのうち再利用するもの、古くなっているもの、残っている不足箇所
• 不明確な領域と、推測せず未解決の質問として記載する内容

コンポーネントの名前から、その動作を推測してはいけません。コードから動作が明確に読み取れない場合は、確信を持った主張ではなく、未解決の質問として扱います。

---

Gate 1 — ドキュメントマップ

アプリケーションの規模に合わせて、作成するドキュメント一式を提案します（小さな CLI に必要なドキュメントは、複数サービスのプラットフォームよりずっと少なくて済みます）。チェックリストとして提示してください。

## Proposed documentation map

### Architecture (docs/architecture/)
- [ ] overview.md      — context, purpose, high-level architecture, tech stack
- [ ] components.md    — each module/service: responsibility, key files, dependencies
- [ ] data-model.md    — entities, stores, schema/migrations, relationships
- [ ] integrations.md  — external systems and internal service-to-service calls
- [ ] deployment.md    — build, environments, CI/CD, runtime topology   (if relevant)
- [ ] diagrams.md      — Mermaid: context, component, key sequences, ERD

### Functional / domain (docs/functional/)        (only if user-facing / domain-heavy)
- [ ] domain.md        — domain concepts, business rules, glossary
- [ ] flows.md         — primary user/business flows end-to-end

• アプリケーションに不要な項目は削除し、必要に応じて固有の項目を追加します。
• **「{scope} のドキュメントマップは以上です。作成を始める前に確認してください。」**と尋ねます。
• 停止します。ユーザーがマップを確認するまで、ドキュメントを作成してはいけません。

隔離の設定（スタンドアロンモードのみ）

incu-way-init 内で実行している場合は、この手順をスキップし、既存の init ブランチに書き込みます。

スタンドアロンで実行している場合は、書き込みを始める前に、作業をどのように隔離するかユーザーに尋ねます。

現在のチェックアウトに新しいブランチを作成して作業しますか、それとも別の git worktree を作成しますか？

ユーザーの回答をそのまま使います。 質問したらそこで停止します。ユーザーが選択するまでは、ブランチも worktree も作成しないでください。

現在のチェックアウトに未コミットの変更がある場合は、ブランチの切り替えや worktree の作成をする前に停止して確認してください。

オプション A — 現在のチェックアウトにブランチを作成

# Run from the repo root
git switch develop
git pull --ff-only
git switch -c docs/{slug}

オプション B — 別の worktree

worktree は .worktrees/ の下にのみ作成してください。パスをユーザーに尋ねないでください。

# Run from the repo root
git fetch origin develop
mkdir -p .worktrees
git worktree add .worktrees/docs-{slug} -b docs/{slug} origin/develop

{slug} は {kebab-scope} です（例：architecture、payments-module）。すべてのドキュメントは、選択した作業場所内で作成・コミットします。

---

フェーズ 2 — ドキュメントの作成

目標： 実際のコードを根拠として、確認済みの各ドキュメントを作成します。

作成ルール（必須）

• 追跡可能であること。 重要な主張にはすべて、その出典（path/to/file.ext:line、モジュール、または設定キー）を明記します。読者がコードで検証できるようにしてください。
• 創作しないこと。 コードが実際に行うことを記述し、「本来こうあるべき」という内容は書きません。動作が不明確な場合は、推測せず Open questions / to verify に記載します。
• 矛盾は記録し、黙って解消しないこと。 コードの異なる箇所同士、またはコードと既存ドキュメントに矛盾がある場合は、その矛盾を明記します。
• 簡潔な文章にすること。 短く、直接的な文にします。冗長な表現は避けます。読みやすい場合は、段落より箇条書きや表を優先します。
• 更新＝整合性の確認。 更新モードでは、古くなった記述を現在のコードに照らして修正し、変更点を明記します。内容を無条件に追加しないでください。

ドキュメントごとの推奨構成

docs/architecture/overview.md：

# Architecture overview — {app name}

## What it is
One paragraph: purpose and who uses it. (source: README / PRD / entry point)

## Tech stack
Languages, frameworks, datastores, infra — each with where it's configured.

## High-level architecture
The shape (layers / services / event-driven / …) and why, with a Mermaid context diagram.

## Module map
| Module | Responsibility | Key path | Talks to |
|--------|----------------|----------|----------|

## Cross-cutting concerns
Auth, config, logging/observability, error handling — where each lives.

## Open questions / to verify
- …

components.md、data-model.md、integrations.md、および対象範囲に含まれる場合は機能ドキュメントにも、同様に追跡可能で表を優先するスタイルを適用します。data-model.md ではスキーマ／マイグレーションファイルを示し、integrations.md では外部システムごとに、呼び出し元のコードを明記します。

---

フェーズ 3 — 図

アプリの規模に合わせて、docs/architecture/diagrams.md に Mermaid の図を作成します。

• コンテキスト／コンテナー — システムと外部アクターおよび依存関係。
• コンポーネント — 内部モジュール／サービスとその関係。
• シーケンス — 最も重要なエンドツーエンドのフローを1～3件。
• ERD — 意味のあるスキーマがある場合は、主要なデータモデル。

終了前に、すべての図が Mermaid パーサーで検証されていることを確認してください。レンダリングされない図は、図がないよりも悪いものです。読みやすさを保ち、図が過密になる場合は、目的を絞った複数の図に分けてください。

---

ゲート 2 — レビュー

ドキュメントと図を作成したら、次の作業を行います。

• 作成した内容と保存場所の一覧を提示し、ドキュメント全体で集めた Open questions / to verify を列挙します。
• 次のように伝えます："docs/architecture/{ および docs/functional/} にドキュメントを用意しました。未解決の質問は、ご確認いただくために一覧にしています。レビューをお願いします。"
• 停止します。先に進まず、ユーザーのレビューを待ちます。

incu-way-init 内で実行している場合は、制御が init フローのゲート 2 に戻ります。ドキュメントはそこでレビューされ、init PR に含まれます。以下のスタンドアロン PR 手順はスキップします。

---

フェーズ 4 — PR（スタンドアロンモードのみ）

incu-way-prepare-pr を呼び出して docs/{slug} をプッシュし、PR を作成するよう提案します。自分でプッシュしたり、gh pr create を実行したりしないでください。

incu-way-prepare-pr で使用する PR タイトル／本文の推奨案：

Title: docs({slug}): document {scope}

PR の本文には次の内容を含めます。

• 対象範囲： ドキュメント化した内容と、その詳細度。
• 一覧： 作成／更新した各ドキュメントへのリンク。
• 未解決の質問： チームの意見が必要な未解決項目。

PR を作成したら、PR の URL を共有します。停止してください。ユーザーの承認を得るまでマージしないでください。

クイックリファレンス — ゲート

ゲート	トリガー	伝える内容	停止する条件
1	マップの提案後	「これは {scope} のドキュメントマップです。執筆を始める前に確認してください。」	ユーザーの確認
2	ドキュメントの執筆後	「docs/architecture/ にドキュメントを用意しました。レビューをお願いします。」	ユーザーのレビュー
3	（スタンドアロン）レビュー後	PR docs/{slug} → develop に incu-way-prepare-pr を使うよう提案し、ユーザーが実行したら URL を共有する	ユーザーの承認

---

作成するもの

docs/
  architecture/
    overview.md        # context, stack, high-level architecture
    components.md       # module/service breakdown
    data-model.md       # entities, stores, schema
    integrations.md     # external + internal integrations
    deployment.md       # build, environments, CI/CD, topology   (if relevant)
    diagrams.md         # validated Mermaid diagrams
  functional/           # only when user-facing / domain-heavy
    domain.md           # domain concepts + glossary
    flows.md            # primary flows end-to-end

---

してはいけないこと

• ゲート 1 でマップの確認を得る前に、ドキュメントを書かないでください。
• 動作、構造、意図をでっち上げないでください。コードで検証できない内容は、 「未解決の質問／要検証」に記載してください。
• 追跡できない主張をしないでください。重要な記述にはすべて、ファイル、モジュール、またはキーを示してください。
• Mermaid パーサーでレンダリングに失敗する図を完成版として扱わないでください。
• incu-way-init から呼び出された場合は、別の PR を作成しないでください。ドキュメントは init PR に含めます。
• スタンドアロンモードでは develop または main に直接書き込まず、docs/{slug} ブランチを使用してください。