# Arch Doc > End-to-end authoring and calibration of an architecture design document from upstream sources. MUST trigger for 写架构设计文档, 架构说明书, ARCH 文档, 软件实现架构说明书, 架构文档补时序图, PlantUML 时序图（架构文档内）, 交叉校准, 回源核对, 上游研读, 上游真源, 最佳实践评审, 架构评审对标, 架构文档模板, PRD 模板, 产品需求文档模板, 功能详细设计模板, 校准架构文档, 质量场景卡, or whenever a repository needs a software-implementation-architecture document drafted, calibrated against upstream design docs, or reviewed against industry best practices. Distilled from the MCC ARCH-2026-001 authoring pipeline. - Skill: `tefuirnever/arch-doc` (Agent Skill, multi-file: 18 files) - Install (CLI): `npx skillmds@latest add tefuirnever/arch-doc` - Raw SKILL.md: https://api.skillmd.com/api/skills/tefuirnever/arch-doc/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Product & Planning - Author: TeFuirnever (https://skillmd.com/u/tefuirnever) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tefuirnever/arch-doc --- # Arch Doc **🦊 阿舟 · Arch Doc** > 先读上游，再写契约，声称不越证据。 把上游真源文档研读成带出处的研究笔记，按模板产出架构契约文档；图只用 PlantUML，每个声称可回源、可证伪。本 skill 沉淀自 MCC ARCH-2026-001 v0.1→v0.17 的完整成文-校准-评审流水线。 ## 启动协议 ```text 🦊 阿舟 · Arch Doc 启动｜mode=｜scope= ``` `draft` 产出新文档；`calibrate` 对照上游校准既有文档；`review` 做最佳实践对标评审；`sequence` 只补时序图。缺上游真源或缺读取权限时，用 `🔒 阿舟暂停这一项` 标记该项，其余继续。 ## 触发与授权 - 明确要产出或重写架构文档：`draft`（内含研读、骨架、成文）。 - 已有文档、上游已演进或事实存疑：`calibrate`。 - 要求对标业界最佳实践或打分：`review`。 - 要求补时序图或校验既有图：`sequence`。 - 只要求评审不要求修改：review 模式只产出报告文件（落盘到目标文档同目录 `REVIEW.md` 或仓库 `evidence/`），不改文档。 - 模式 → 步骤映射：draft = 1→2→3→4→6；calibrate = 1（增量）→5→6；review = 独立评审线（报告模板见 review-guide）；sequence = 4→6。 ## 六步工作流 每步以完成判据收口；判据未满足时不进入下一步。 ### 1. 研读真源 → 研究笔记 真源有两种，常需并用：**上游设计文档**（全量精读）与**代码仓库**（代码是唯一现役答案——入口文件、模块树、调用链、接口定义、测试即行为证据）。产出研究笔记，每条事实一行并注明出处与关键原文；笔记格式与存疑纪律以 [references/calibration-guide.md](references/calibration-guide.md) 一、为准。两源冲突时以代码为现役答案并标注分歧。 完成判据：笔记覆盖上游全部文档；零无出处事实；存疑项有显式标注。多域上游时可并行分工（概念域 / 设计稿域 / API 与配置域 / 指南与集成域），每域一份笔记。 ### 2. 选剖面成骨架 从 [references/templates/](references/templates/) 选剖面，选择规则以 [design-doc.md](references/templates/design-doc.md)（模板选择权威元文档）为准；可实例化剖面：软件实现架构用 `software-implementation-architecture.md`，产品需求用 `prd.md`，功能详设用 `feature-detailed-design.md`。骨架分两部分。**模板章节**（实体在所选剖面内）：文档控制与证据状态词表、原则与不变量、分层视图、运行流程、威胁表、容量预算、评审门、变更记录。**skill 附加件**（模板外判据，生成文档时补齐于正文，不算改模板）：利益相关方-视图索引、词汇表、追溯矩阵、读者指南与用词约定、时序图要求。 完整性与结构判据以 [references/format-standard.md](references/format-standard.md) 为准（对标 ISO/IEC/IEEE 42010 / 1016 / arc42）。 完成判据：骨架章节齐全且满足 format-standard 完整性判据；文档控制表含「模板来源」行，回链所选模板剖面（对应 [references/templates/PROVENANCE.md](references/templates/PROVENANCE.md) 条目）。 ### 3. 成文与措辞纪律 每个声称可证伪——都能指出哪个验证能推翻它。治理术语（真源、派生面、Receipt、Seam、锚点、冻结）在词汇表唯一定义，正文引用不另定义。文档声称的状态不得高于证据所能支撑的状态，用词取所选模板的证据状态词表：Implemented 不写 Verified，Planned（目标态）不写 Production。目标态内容（未实现的设计契约）显式标注「目标态」，与现状分开陈述（与 `Planned` 的同义对应见 [references/format-standard.md](references/format-standard.md)）。 完成判据：状态词全部来自 §0 词表；全文零未定义治理术语；目标态与现状无混排。 ### 4. 图纪律 PlantUML 是文档唯一权威图形式。每张图带四联注：目的 / 范围 / 版本日期 / 结论；图注版本号必须存在于变更记录（图注版本必须入账）。时序图的完整规范——片段条件标签、同步/异步箭头语义、参与者与消息密度、映射行、放大图纪律——以 [references/sequence-guide.md](references/sequence-guide.md) 为唯一清单。 完成判据：`@startuml` 与 `@enduml` 配平；四联注齐全且版本入账；每张时序图逐项通过 sequence-guide 的自查清单。 ### 5. 回源交叉校准 用另一条评审线把文档事实逐条对照上游原文，输出勘误清单（位置 / 文档现文 / 上游原文 / 修正动作）并应用。典型坑：上游文档自身矛盾（双口径并存并标注）、目标态混排成现状、实施参数随上游版本漂移（处理规则见 [references/calibration-guide.md](references/calibration-guide.md) 二、6 与下方边界）。 完成判据：勘误清单为空，或每条已应用并复验。 ### 6. 评审对标与入账 按 [references/review-guide.md](references/review-guide.md) 做结构线与技术线对标评审，输出评分、按严重度排序的发现、可落地改进清单（动作 / 章节 / 收益 / 工作量 S-M-L）。收尾确定性校验全绿才算完成：运行 `/scripts/verify_doc.py <文档.md>`（配平 / 链接 / 图注版本入账 / changelog 有序 / 空白；可选 `--plantuml-cli` 渲染门、`--trace-prd/--trace-detail-dir` 追溯门、`--states` 状态词提示），状态词与驱动场景映射人工复核。新文档起步用 `/scripts/new_doc.py` 从只读模板脚手架实例化；ADR 用 [references/adr-template.md](references/adr-template.md)。 多阶段事件协议（启动行 / 状态前缀 / 收据 schema / Unicode 降级）见 [references/brand-layer.md](references/brand-layer.md)；可选依赖与边界见 [references/setup.md](references/setup.md)。 全绿输出 `✅ 验证通过`；任一 gate 失败输出 `❌ 验证失败` 并列出具体 gate。评审发现只入改进清单，未经用户点名不扩权修改。 ## 边界 - 产出物 = **Markdown 正文 + PlantUML 图**：正文 `.md`，全部图以 PlantUML 源码内嵌输出，不引入其他图形格式。独立的图表文件请求（.excalidraw / .svg 单文件交付）让位 `excalidraw-diagram`，本 skill 只负责文档内 PlantUML。 - 模板只读：[references/templates/PROVENANCE.md](references/templates/PROVENANCE.md) 以 SHA-256 锁定原版；发现偏差先恢复模板，再修自己的文档。 - 实施参数随上游版本漂移：正文保留架构事实与指针，参数进附录并标失效条件（细则见 [references/calibration-guide.md](references/calibration-guide.md) 二、6）。 - Emoji 只属于展示层；文件名、字段、状态枚举、收据与校验名保持纯文本。引用原始证据（原文、commit、报告链接），不引用转述作为证据。 - Host 不支持 Unicode 时，品牌标记退化为纯文本（`验证通过` / `验证失败` / `暂停`），语义不变。 - 产出语言跟随用户请求语言；中文剖面模板按原结构组织，正文按请求语言书写。 - 引用上游品牌名仅限事实表与出处路径；图内使用中性称谓并在词汇表声明映射。 ## 交付收据 mode、源文档与产物路径、已跑校验清单（链接 / 配平 / changelog / 状态词）、评审对标分数与 Top 发现、holds 与一个具体 next action。 ## References - [references/templates/software-implementation-architecture.md](references/templates/software-implementation-architecture.md)（ARCH 剖面） · [design-doc.md](references/templates/design-doc.md)（模板选择权威元文档，非骨架） · [feature-detailed-design.md](references/templates/feature-detailed-design.md) · [prd.md](references/templates/prd.md) · [industry-best-practice-baseline.md](references/templates/industry-best-practice-baseline.md) — 来源与版本锁见 [templates/PROVENANCE.md](references/templates/PROVENANCE.md) - [references/sequence-guide.md](references/sequence-guide.md) — 时序图业界规范与自查清单 - [references/calibration-guide.md](references/calibration-guide.md) — 上游研读与回源交叉校准方法 - [references/review-guide.md](references/review-guide.md) — 最佳实践对标框架与改进清单模板 - [references/format-standard.md](references/format-standard.md) — 输出格式规范（42010 / 1016 / arc42 完整性判据） - [references/history-evolution.md](references/history-evolution.md) 与 [references/evolution-contract.md](references/evolution-contract.md) — 证据驱动演化（用户点名 `evolve` 时进入） - [references/templates/PROVENANCE.md](references/templates/PROVENANCE.md) — 模板只读锁（来源与 SHA-256）