map

Map

你正在运行 map 入口流程。你的工作是理解现有代码库，并生成一套不断完善的 CONTEXT.md 层级结构，让 architect、triage 和 verify 能够开展工作。你要记录现状，包括其中的技术债务。你不负责设计应该如何改进——那是 architect 的工作。

运行辅助脚本

此技能将辅助脚本放在自己的 scripts/ 目录中（与此 SKILL.md 一同安装）。将 SKILL_DIR 设置为此技能的绝对路径——该路径显示在本文件末尾的 此技能的基础目录处——然后从项目根目录运行脚本（这些脚本会处理项目的 .changes/ 和 CONTEXT.md 文件）：

SKILL_DIR="<absolute path to this skill's directory>"

以下所有 node "$SKILL_DIR/scripts/..." 命令都依赖此设置。切勿引用 packages/build/——该路径仅存在于工具包的开发仓库中，不存在于已安装的技能中。

你的立场

描述现状，不提出指示。按照代码库的实际情况进行梳理。发现不理想之处时：

• 将其记录在 Known-soft-spots 中。
• 除非有充分证据表明该模式是承载关键依赖的（例如外部使用方依赖它、它具有契约性等），否则将其牢固度标记为 soft。
• 不要向用户建议改动——本次工作是编写文档，而不是制定重构计划。

保持保守的牢固度判断：不确定时标记为 soft。以后要将其升级为 firm 很容易；错误地标记为 firm 再降级则会造成干扰。

信息收集

在进行任何上下文扫描、仓库探索、子 Agent 工作或参考资料阅读之前，先获取目标和可观察结果、受影响范围、约束和反目标，以及需求是已明确、部分明确还是尚未明确。只梳理支持上述信息收集所需的范围。

阶段 1：探索

运行上下文探索扫描，查找所有现有的 CONTEXT.md 文件：

node "$SKILL_DIR/scripts/context-discover.mjs"

然后使用探索子 Agent 理解代码库结构。请拆分工作：

探索 Agent 1——系统层面：

“探索此代码库。识别顶层组件及其职责、主要数据流、技术栈、组件之间显而易见的边界，以及任何配置或环境依赖。请以结构化摘要汇报。”

探索 Agent 2——构建和测试基础设施：

“探索此代码库。识别其构建方式、测试的组织和运行方式、所用测试框架，以及现有测试覆盖情况。请汇报结果。”

针对每个顶层组件（有多个时并行开展）：

“探索 目录／模块。识别其公共接口、内部结构、对其他组件的依赖、读取的任何配置，以及显而易见的技术债务或已知的不理想模式。请汇报结果。”

阶段 2：根目录 CONTEXT.md

根据探索结果，使用 references/templates/CONTEXT.md.tmpl 和 --root 编写根目录 CONTEXT.md。

关键决策：

• 边界牢固度： 倾向于标记为 soft。只有对外部使用方有契约约束的边界（已发布的 API、供外部使用方使用的 IPC 协议、供外部用户使用的文件格式）才标记为 firm。
• Known-soft-spots： 如实、具体地记录。这是对后续 Agent 最有价值的字段，能让它们明确知道可以改进哪些地方。
• 术语表： 记录代码中实际使用的领域术语，而不是理想定义。使用代码库中出现的名称。
• 技术要求： 只有存在证据支持的硬性约束才纳入。“应该足够快”不是技术要求。“根据 config/sla.yaml 中的 API 合同，每个 API 的延迟 p99 必须低于 50ms”才是。

创建脚手架并填写：

node "$SKILL_DIR/scripts/context-scaffold.mjs" --path . --name "<Project Name>" --root

然后填写所有章节。除非能从代码中识别出明确且可由外部观察的行为契约，否则将 Acceptance/Behavioral Criteria 留空。

阶段 3：组件 CONTEXT.md 文件

为每个顶层组件创建框架并填写 CONTEXT.md：

node "$SKILL_DIR/scripts/context-scaffold.mjs" --path <component-dir> --name "<Component Name>"

根据 explore Agent 的报告填写每个字段。应用相同的保守确定性规则。

对于每个组件，请询问：

• 该组件的单一职责是什么？（如果有两个职责，请在 Known-soft-spots 中注明。）
• 它面向其他组件的公共接口是什么？
• 它依赖什么？
• 如果它发生变化，会造成什么影响？

阶段 4：有效性检查

启动一个子 Agent：

“你正在审查根据代码库分析生成的 CONTEXT.md 文件。对于每个 CONTEXT.md，请检查：其中的说法是否符合你在代码中看到的内容？是否遗漏了边界？是否有标记为稳固、但看起来并未对外约定的边界？Known-soft-spots 中是否遗漏了明显的技术债务？请报告差异。”

将所有生成的 CONTEXT.md 文件和 explore 报告交给子 Agent。

在最终确定前解决这些差异。

阶段 5：标记来源信息

用户审查并批准 CONTEXT 文件后，为每个文件标记当前 HEAD SHA：

git rev-parse HEAD

更新每个 CONTEXT.md 中的 Provenance: validated-at: 行。

阶段 6：向用户展示

展示：

• 根 CONTEXT.md
• 已创建的组件 CONTEXT.md 文件列表
• 稳固边界与软边界的数量
• Known-soft-spots 清单（最具可操作性的输出）

请用户审查并纠正任何误解。用户了解代码库；你不了解。请相信用户的更正。

map 不做什么

• 它不会提出架构改进建议（这是 architect 的工作）。
• 它不会为代码更改创建变更清单。
• 它不会运行测试。
• 它不保证 CONTEXT.md 完整无缺——这只是尽力推导的结果。未来的 verify 轮次以及 architect/triage 会话会进一步完善它。

map 之后

告诉用户：

“CONTEXT.md 层级结构已就绪。现在你可以使用 architect 开发新功能，使用 triage 处理 Bug 和小型更改，或使用 verify 在代码不断演进时保持文档同步。”

参考文件

• references/context-schema.md — CONTEXT.md 字段和确定性规则
• references/templates/CONTEXT.md.tmpl — 模板
• references/drift-control.md — 来源信息和过时模型
• references/seam-and-test-taxonomy.md — 边界确定性指南