contextualizar-repo

使存量项目清晰易懂（brownfield）

目标

让现有系统像 greenfield 项目一样清晰：确保之后到来的任何 Agent 或人员，都能找到关于如何启动系统、系统如何构建、继承了哪些决策、应模仿和避免哪些模式、技术债务在哪里，以及修改系统时必须遵守哪些规则的书面说明。

此技能涵盖技术上下文（第 1、2 和 5 层）。功能上下文（功能、业务规则和术语表）由 BA 使用 contextualizar-negocio 编写文档。

**此技能不会修改代码，也不会修复技术债务。**它只负责阅读、评估、记录、提问，然后停止。

原则

1. **没有证据，就不作断言。**关于系统的每项陈述都必须注明 文件:行号、附带输出的命令，或标记为 NO VERIFICADO。
2. **现有文档是信息来源，不是真相。**阅读 README、AGENTS.md、CLAUDE.md 或以前的文档，并逐项对照代码验证所有复用的陈述。
3. **描述代码的实际情况，而非应有的情况。**改进建议应写入技术债务地图，不能与现状描述混在一起。
4. **不作出新的架构决策。**记录已有的决策。如果存在多种并行模式，由人工确认应采用哪种规范。

输入

• 仓库路径（默认为当前目录）。
• 现有文档（如有）：README*、AGENTS.md、CLAUDE.md、docs/、以前的 ADR。
• 可选：团队最关注系统的哪一部分（以便优先深入了解）。

工作流

1. 让项目易于理解（第 1 层）

1. 找出如何安装、启动和测试项目：package.json（或同类文件）、README、Dockerfile、docker-compose*、现有文档。
2. 验证每条命令：如果用户授权，就运行命令并记录结果和耗时。如果不运行，则标记为 NO VERIFICADO。
3. CodeGraph 索引：
   • 如果已安装 codegraph：运行 codegraph init（如果 .codegraph/ 已存在，则运行 codegraph index）。记录耗时。
   • 如果未安装：建议安装（参阅其最新文档），并在不使用它的情况下继续；注明依赖关系图是通过阅读代码整理的。
   • 在后续步骤中使用索引分析依赖关系、影响范围和调用方。

2. 绘制实际分层结构图（第 2 层）

1. 遍历文件夹结构，为每个文件夹标注观察到的职责。
2. 跟踪一个典型的端到端流程（从请求进入到访问数据的全过程），并记录经过的每个文件。该流程用于验证分层结构图。
3. 指出存在两代实现的层（例如，旧版和新版前端）。

3. 继承的决策（第 2 层）

1. 识别已作出的结构性决策：持久化、扩展机制、通信协议、身份验证、模块组织方式、测试策略。
2. 使用 assets/adr-heredado-template.md（如果已安装 generar-tech-design，则使用其模板），为每项决策编写一份 ADR，状态设为 Aceptado (heredado)。从 adrs/ 中下一个可用的编号开始编号。
3. 决策部分描述代码已有的做法，并提供证据。后果部分至少包含一项该决策当前带来的实际成本。

4. 模式目录（第 2 层）

对于每个相关主题（如何添加 endpoint 或路由、数据访问、错误处理、配置、依赖、测试、模块组织、可见文本、扩展）：

1. 识别解决该主题的共存方式有多少种，为每种方式提供一个 文件:行号 示例，并估算使用次数。
2. 提出哪种方式是规范（应模仿），哪种是遗留（不应模仿），并说明判断标准：项目文档的建议、最新代码的用法，或新代码中的多数用法。
3. 如果没有明确标准，不要选择：将其列为待人类确认的问题。
4. 明确说明依赖是如何连接的（注入还是直接导入），以及这会对代码测试产生什么影响。

5. 债务地图（第 2 层）

记录每项发现，不要修复，并注明：ID、描述、证据、风险（高 · 中 · 低）以及适合处理的时机（通常是在某项功能涉及该处时）。

至少检查以下内容：

• 体积过大或职责过多的文件或模块；
• 执行同一操作的重复路径；
• 无法删除的遗留兼容代码；
• 团队自行声明的债务（TODO、FIXME、HACK）；
• 弱类型或缺失的验证；
• 高耦合（许多文件依赖同一个文件），如果可用则使用 CodeGraph。

性能：仅记录待测量的候选项，绝不在没有测量的情况下将其认定为已确认的 bug。

6. 构建规则（第 5 层）

从规范和继承的 ADR 中推导规则。每条规则都要包含：

• 规则内容（“新功能应作为插件实现”）；
• 来源（ADR、规范模式或项目文档）；
• 验证方式：一条命令、一种工具或现有测试。

如果规则无法验证，则将其标记为软规则，并提出验证方式（lint、测试或使用 crear-guardrail 设置防护机制），但不要创建它。

7. 编写

文件	内容	模板
docs/contexto/ARQUITECTURA.md	已验证的启动和测试流程、分层地图、端到端流程	assets/arquitectura-template.md
docs/contexto/PATRONES.md	规范与遗留模式目录	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. 人工关卡

提供摘要和待定决策：

• 每个存在多种模式的主题中，待确认的规范；
• 软规则及其建议的验证方式；
• 所有标记为 NO VERIFICADO 的内容。

等待明确批准。 人类批准前，不得使用这些上下文，也不得将其传达给其他 Agent。

10. 与 BA 协调

如果会话中有 BA（参见 invoke-agent），则在获得批准后：

• 发送 技术上下文已就绪：<文档/上下文和 adrs 的路径> — <未解决事项>。
• 收到 BA 发送的 GLOSARIO: TÉRMINOS NUEVOS 后，为 docs/contexto/GLOSARIO.md 中的每个术语补充“所在位置”列，并附上证据，然后回复 GLOSARIO COMPLETO。
• 同一分歧最多讨论两轮；之后由人工决定。

约束

• 不修改项目代码、配置或依赖项。
• 不处理技术债，即使问题很简单也不处理。
• 如果标准不明确，不自行选择规范；应先询问。
• 未经批准，不覆盖现有文档。
• 人工把关前，不与其他 Agent 沟通。