incu-way-docs

代码库文档编写流程

一种由关卡驱动的工作流，用于将现有代码库转化为清晰、可追溯的文档：应用是什么、如何构建、各部分如何协同，以及——如果它是一个具有面向用户行为的产品——它在功能上能做什么。输出存放在 docs/architecture/（必要时也包括功能／领域文档）中，供其他 incu-way 流程在 Phase 0 中读取。

两种调用模式：

• 作为 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、功能目录、微服务等）。
• 数据存储——数据库、缓存、队列、Blob 存储；架构／迁移文件的位置。
• 外部集成——第三方 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

仅在 .worktrees/ 下创建 worktree。不要询问用户要使用哪个路径。

# 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、模块或配置键。读者必须能够在代码中核实。
• 不臆测。 记录代码的实际行为，而非它“应该”如何运行。如果行为不明确，将其写入待解决问题／待验证事项——绝不猜测。
• 记录冲突，不要悄悄解决。 如果代码的两个部分（或代码与现有文档）相互矛盾，请明确记录该矛盾。
• 行文简洁。 句子要简短、直接。不要写冗余内容。适合时优先使用项目符号和表格，而非段落。
• 刷新 = 对照核实。 在刷新模式下，根据当前代码更新过时说明并标明变更；不要盲目追加内容。

每份文档的建议结构

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 道关卡 — 审查

文档和图表编写完成后：

• 提供索引（说明产出了哪些内容，以及它们的位置），并列出各文档中汇总的待解决问题／待验证事项。
• 请说：“文档已准备就绪，位于 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	（独立模式）已审核	建议使用 incu-way-prepare-pr 为 PR 创建 docs/{slug} → develop；用户运行后分享 URL	用户批准 PR

---

产出内容

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——文档会随初始化 PR 一起提交。
• 独立模式下，不要直接写入 develop 或 main；请使用 docs/{slug} 分支。