ln-72-current-architecture-documenter

当前架构文档编写器

目标： 生成一份可信的快照，记录已检出仓库中实际实现的架构。说明现有内容及其行为；不要评估优劣、规定目标架构、修复代码，也不要把预期中的图示当作事实。

执行约定： 有序复选框即为完成定义。内部跟踪每一项的状态：PENDING、有具体证据支持的 PROVEN、有证据表明条件不存在的 CLEARED，或存在缺口的 UNPROVEN；阅读、委派或工具故障都不构成证明。每完成一个章节后都要重新核对各项。返回前，解决所有 PENDING 项，并且只统计 PROVEN 和 CLEARED 项；对每个缺口应用此技能的判定和审批规则。 保留用户意图、范围和现有授权。继续已获授权的工作；仅针对尚未解决且影响重大的选择或所需的外部审批提出询问。根据实际风险调整深度，不得悄然跳过检查。保留依赖关系和安全顺序；除此之外，为每项义务选择恰当的验证方法。

工具路由

需求	首选能力	后备方案
快照身份和工作区状态	Git 状态、分支、远程仓库和 HEAD	将提供的快照记录为 UNVERIFIED
结构和配置	原生列表、搜索、清单和直接读取文件	有针对性的手动检查
符号、依赖项和使用方	语言智能或已解析的依赖工具	搜索定义、注册项、导入和调用方
运行时和部署拓扑	入口点、IaC、容器、CI、配置和运行时证据	将部署关系标记为 UNKNOWN
文档修改	对已批准的架构文档进行最小化补丁修改	若无已授权的可写路径，则返回 BLOCKED

优先使用本地证据，而非远程仓库状态。路径、图示或命名约定只是线索，除非可执行接线或权威契约予以确认。

产物规则

• 复用清晰的现有当前状态架构文档；否则使用 docs/architecture/current-state.md。
• 将文档锚定到远程仓库、分支、HEAD、工作区状态和观察日期。
• 使用文件路径、符号、命令或配置键为重要主张提供依据。
• 将主张标记为 OBSERVED、DOCUMENTED、INFERRED 或 UNKNOWN。
• 将实际结构与预期目标设计、审计发现分开。
• 先以粗略粒度绘制声明的系统范围，再仅深入说明其关键行为；不要把范围有限的请求扩展为整个仓库的清单。
• 优先描述职责，而非穷举文件清单。
• 记录证据截止范围，以便读者区分未检查范围和确实不存在的内容。
• 仅在易变的计数或清单影响架构理解时保留它们。

检查清单

1. 明确文档约定

• 确定仓库范围、目标读者、已批准的目标位置、所需深度和语言。
• 阅读仓库说明，并记录快照身份及工作区未提交更改带来的限制。
• 搜索现有的当前状态、基线、目标设计、决策、图示和部署产物。
• 复用明确无歧义的当前状态文档，或选择默认路径，避免重复项目知识。
• 除已批准的架构文档外，本次运行均保持只读。

2. 梳理系统全貌

• 根据清单文件和 CI，识别语言、框架、包根目录、生成的表面，以及规范的构建或运行命令。
• 识别用户、外部系统、入口点、应用、服务、进程、工作进程、计划任务和部署单元。
• 梳理主要领域或模块、职责、归属关系和依赖方向。
• 梳理数据存储、缓存、队列、文件、外部 API、架构定义和权威数据源。
• 记录公共接口、运行时发现、注册、配置组合和环境边界。
• 记录构建、部署、扩缩容和故障边界，不要仅凭目录名称推断独立性。

3. 追踪关键行为

• 根据业务重要性和架构影响范围，选择具有代表性的关键流程。
• 追踪每个流程从参与者或触发器，经入口点、运行时协调、领域行为、持久化或集成，到可观察结果的全过程。
• 在有证据支持时，记录同步和异步跳转、事务归属、一致性、重试、超时、幂等性和错误传播。
• 根据仓库证据，描述部署、启动、关闭、运行状况、可观测性和恢复路径。
• 仅深入分析会影响架构理解的复杂或不确定子系统；不要将常规实现细节写入架构文档。

4. 编写当前状态文档

• 编写快照标识、系统上下文、组件清单、职责、依赖与数据流、运行时拓扑、关键流程、部署、归属关系和证据索引。
• 在文档中加入最低限度且有用的图表，或按路径链接到现有图表文件。
• 区分已观察到的实现和文档描述的意图，并明确列出差异或矛盾，不评定严重程度。
• 除非有权威证据支持，否则将仅存在于远程、仅在运行时可见、组织层面或生产环境中的事实标记为 UNKNOWN；区分已声明的部署配置与实际观察到的在线拓扑。
• 保留有来源的人工维护上下文及其证据状态；记录矛盾，并标记缺乏支持的历史说法，不要将其作为已观察事实沿用。

5. 验证并报告

• 根据已检查的快照证据验证每条引用，并删除缺乏支持的说法；只有在来源发生变化或先前检查未能证实相关说法时，才重新查看来源。
• 确认这份梳理能说明如何发现、执行、持久化和部署关键行为。
• 确认未混用抽象层级，且正文和图表中的名称保持一致。
• 当快照有证据支持且内容有用时，使用 DOCUMENTED；当重要拓扑仍未知时，使用 INCONCLUSIVE；当无法安全确认仓库身份、范围或目标位置时，使用 BLOCKED。

自检

• 提交前核对。 检查各项证据、需求覆盖情况、矛盾、范围、结论和适用的清理事项。修正报告或获准修改的文件。复用有效证据；不要自动重新扫描仓库或重新运行已成功的命令。仅针对相关变更、失败或尚未解决的证据重复检查。说明仍未解决的问题。

输出约定

按用户使用的语言依次报告；保留全部五个字段，并且每项事实只陈述一次。简短结果可为每个字段写一行；省略空表格，不要复制链接的产物：

1. 结果： 针对技能的结论及有依据的结果。
2. 范围： 已审查／更改的范围、排除项、基线和重要假设。
3. 证据： 以下针对技能的字段；区分事实、推断和未经验证的声明。链接产物；适用时使用表格。
4. 验证： 检查／结果、无法获取的证据，以及适用的清理工作／外部状态。
5. 完成情况： Checklist: X/Y complete；Incomplete: None，或列出每个 UNPROVEN 项的原因、对结果的影响和确切的下一步操作；残留风险及所需决策。

针对技能的证据： 产物路径和快照标识（远程端、分支、HEAD、工作区、日期）；映射的上下文、模块、运行时／部署、数据／接口、所有权和关键流程。指出已更改的章节／图表，以及需要运行时、组织或外部确认的声明或范围，并注明其状态、检查过的证据和确切的下一步操作。