fmway-docs

用途

fmway-docs 用于为已存在的代码库（brownfield）产出或刷新架构文档与功能文档，使代码结构、数据模型、外部集成、部署方式以及（在适用时）业务领域概念与用户流程变得清晰且可追溯。它既是独立流程，也可作为 fmway-init 的组成部分。产出的文档是其他 fmway 流程在「Fase 0」读取的上下文。

主要能力

只读盘点：先在不写文档的前提下确认范围与深度（整个仓库，或某个模块/服务/上下文；仅架构，或架构+功能/领域；新建还是刷新），阅读已有 README、docs/、PRD 等资料，避免重复并识别过时内容。
代码清单梳理：盘点语言/框架/运行时、入口点、模块分层、存储（数据库、缓存、队列、文件存储及 schema 与迁移位置）、外部集成、构建/运行/测试/部署方式、横切关注点（认证、配置、日志与可观测性、错误处理）。
文档地图确认（Gate 1）：以清单形式提出拟产出的文档集合，按应用规模裁剪，用户确认后才开始撰写。
可追溯写作：每条非平凡论断都指向源码路径/行号、模块或配置键；不臆测行为，不清晰之处列入「待验证的开放问题」；冲突显式记录而非静默消解；文字简洁，优先用列表与表格。
Mermaid 图表：生成上下文/容器图、组件图、1–3 条关键端到端时序图、核心数据模型 ER 图，并要求通过 Mermaid 解析器校验，过载图表应拆分。
评审（Gate 2）：交付索引与汇总的开放问题，等待用户评审。
PR 流程（仅自主模式）：建议调用 fmway-pr 推送 docs/{slug} 并在 develop 上开 PR，PR 正文包含范围、索引与开放问题；不自行 push 或执行 gh pr create，不合并直到用户批准。

使用方式

两种调用模式：

作为 fmway-init 的一部分（brownfield 接入）：写入当前 init 分支或 worktree，文档随初始化 PR 一起提交，不另建分支或 PR。
单独运行（刷新或为某模块写文档）：docs/{slug} 为独立分支 → 向 develop 提 PR。

单独运行时需先询问用户如何隔离工作，并按选择执行（仅在用户选择后创建分支或 worktree；如当前有未提交改动需先停下询问）：

选项 A — 在当前检出中建分支： git switch develop && git pull --ff-only && git switch -c docs/{slug}
选项 B — 独立 worktree（仅允许建在 .worktrees/ 下）： git fetch origin develop && mkdir -p .worktrees && git worktree add .worktrees/docs-{slug} -b docs/{slug} origin/develop

{slug} 为范围的 kebab-case 形式（如 architecture、modulo-pagos）。该流程不维护 .ways/state.json（该模型用于 feature/bug/security 工作）。

产出结构

docs/
  architecture/
    overview.md         # 上下文、技术栈、高层架构
    components.md       # 模块与服务拆分
    data-model.md       # 实体、存储、schema
    integrations.md     # 外部与内部集成
    deployment.md       # 构建、环境、CI/CD、拓扑（如适用）
    diagrams.md         # 经校验的 Mermaid 图表
  functional/           # 仅当面向用户或领域较重时
    domain.md           # 领域概念 + 术语表
    flows.md            # 主要端到端流程

适用场景

接手或接手他人遗留代码库，需要快速建立架构与功能全貌。
已有文档过时，需要对照当前代码进行刷新与对账。
只想为某个模块或服务补充可追溯的架构说明。

限制与约束

Gate 1 前不得写文档；用户不确认文档地图则不进入撰写。
不得编造行为、结构或意图；凡不可在代码中验证的内容均归入「开放问题 / 待验证」。
不得做不可追溯的论断；不得关闭无法通过 Mermaid 解析器渲染的图表。
被 fmway-init 调用时不单独开 PR，文档随初始化 PR 走。
自主模式下不得直接写入 develop 或 main，必须使用 docs/{slug} 分支。
具体运行环境依赖、支持的框架范围、性能表现等资料未提供，暂未提供。