用途
本技能用于将已有的（brownfield）代码仓库整理成与全新项目（greenfield）同等清晰的状态：让之后到来的任何智能体或人员都能找到关于系统如何启动、如何构建、继承了哪些决策、应模仿哪些模式、不应模仿哪些模式、技术债在哪里以及改动时须遵守哪些规则的书面记录。
本技能覆盖技术上下文（第 1、2、5 层）。功能上下文（能力、业务规则和术语表）由 BA 通过 contextualizar-negocio 记录。
本技能不修改代码，也不修复技术债。它只阅读、测量、记录、提问，然后停止。
原则
- 无证据不下结论。关于系统的每项断言都须附带文件:行、带输出的命令，或标记为 NO VERIFICADO（未验证）。
- 现有文档是来源，不是真相。README、AGENTS.md、CLAUDE.md 或既有 docs 会被阅读，但每项被复用的断言都要对照代码验证。
- 描述代码是什么，而非应该是什么。改进建议放入技术债地图，绝不与描述混在一起。
- 不做出新的架构决策。只记录继承的决策。当多种模式并存时，选定 canon 须由人确认。
输入
- 仓库路径（默认为当前目录）。
- 现有文档（如有）：README*、AGENTS.md、CLAUDE.md、docs/、既有 ADR。
- 可选：团队最关心的系统部分（以便优先深入）。
工作流程
1. 使其可读（第 1 层）
找到如何安装、启动和测试：package.json（或等价物）、README、Dockerfile、docker-compose*、现有文档。
验证每条命令：若用户授权，运行并记录结果与耗时。若未运行，标记为 NO VERIFICADO。
CodeGraph 索引：
- 若已安装 codegraph：运行 codegraph init（或若已存在 .codegraph/ 则运行 codegraph index）。记录耗时。
- 若未安装：建议安装（参见其现行文档），并在没有它的情况下继续，同时写明依赖地图是通过阅读代码构建的。
在后续步骤中使用该索引来查询依赖、影响和调用方。
2. 真实分层地图（第 2 层）
遍历文件夹结构，为每个目录分配其观察到的职责。
跟踪一条典型的端到端流程（一个请求从进入到触及数据），记录它经过的每个文件。该路径用于验证地图。
指出存在两代并存的层（例如旧前端和新前端）。
3. 继承的决策（第 2 层）
识别已做出的结构性决策：持久化、扩展机制、通信协议、认证、模块组织、测试策略。
为每项决策写一份 ADR，状态为 Aceptado（heredado），使用 assets/adr-heredado-template.md（或若已安装则使用 generar-tech-design 的模板）。从 adrs/ 中下一个可用编号开始编号。
决策部分描述代码当前实际行为，并附证据。后果部分至少包含该决策今天实际付出的一个成本。
4. 模式目录（第 2 层）
对每个相关主题（如何新增端点或路由、数据访问、错误处理、配置、依赖、测试、模块组织、可见文本、扩展）：
- 检测解决该主题有多少种不同方式并存，每种给出一个文件:行示例和大致使用次数。
- 提出哪个是 canon（应模仿），哪个是 legacy（不应模仿），并声明标准：项目文档推荐、最新代码使用，或新代码中的多数用法。
- 若没有明确标准，则不选择：留作向人提出的问题。
明确包含依赖如何连接（注入还是直接导入）以及这对代码可测试性的后果。
5. 技术债地图（第 2 层）
记录而不修复每项发现，包含：id、描述、证据、风险（高·中·低）以及何时适合处理（通常是：当某个功能经过那里时）。
至少查找：
- 过大或职责过多的文件或模块；
- 做同一件事的重复路径；
- 无法删除的遗留兼容；
- 团队自己声明的债（TODO、FIXME、HACK）；
- 弱类型或缺失的校验；
- 高耦合（许多文件依赖一个），若可用则使用 CodeGraph。
性能：只登记待测量的候选，绝不登记未经测量的已确认 bug。
6. 构建规则（第 5 层）
从 canon 和继承的 ADR 推导规则。每条规则包含：
- 陈述（“新功能以插件形式添加”）；
- 来源（ADR、canon 模式或项目文档）；
- 如何验证：一条命令、一个工具或一个现有测试。
若某条规则无法验证，标记为软规则，并建议如何验证（lint、测试或使用 crear-guardrail 的护栏），但不创建它。
7. 编写
| 文件 | 内容 | 模板 |
|---|---|---|
| docs/contexto/ARQUITECTURA.md | 已验证的启动与测试、分层地图、端到端流程 | assets/arquitectura-template.md |
| docs/contexto/PATRONES.md | canon 与 legacy 目录 | assets/patrones-template.md |
| docs/contexto/DEUDA.md | 技术债地图 | assets/deuda-template.md |
| adrs/NNNN-*.md | 继承的决策 | assets/adr-heredado-template.md |
| AGENTS.md | 简短索引 + 构建规则 | assets/agents-md-template.md |
若已存在 AGENTS.md，不覆盖：提出修改建议，由人决定。
AGENTS.md 将术语表和能力的入口指向 docs/contexto/，即使这些文件由 BA 完成。
8. 自验证
在呈现任何内容之前：
- 重新打开每个引用的文件:行，确认其内容与断言一致。
- 确认每条记录的命令都已运行或标记为 NO VERIFICADO。
- 确认没有任何改进建议被写成描述。
- 建议人进行交叉审查：从干净会话运行 audit-agent-context，最好用另一个模型，以免上下文自我验证。
9. 人工门禁
呈现摘要和待决事项：
- 每个存在多种模式的主题中待确认的 canon；
- 软规则及其建议的验证方式；
- 所有标记为 NO VERIFICADO 的内容。
等待明确批准。在人工批准之前，此上下文的任何内容都不得使用或传达给其他智能体。
10. 与 BA 协调
若会话中有 BA（见 invoke-agent），在批准后：
- 发送 CONTEXTO TÉCNICO LISTO: <docs/contexto 和 adrs 的路径> — <未决点>。
- 当 BA 发送 GLOSARIO: TÉRMINOS NUEVOS 时，为 docs/contexto/GLOSARIO.md 中每个术语的“Dónde vive”列填写证据，并回复 GLOSARIO COMPLETO。
同一分歧最多两轮；之后由人决定。
约束
- 不修改项目的代码、配置或依赖。
- 不修复技术债，即使微不足道。
- 当标准不明确时不选择 canon：提问。
- 未经批准不覆盖现有文档。
- 在人工门禁之前不与其他智能体通信。
适用场景
适用于接手遗留系统、需要让后续智能体或人员快速理解现有项目、建立 AI-first 工作上下文的场景。
限制
本技能不修改代码、不修复技术债、不做出新架构决策，也不覆盖现有文档。所有未验证内容均明确标注。