Communitygithub.com

仓库上手教练

提供基于证据的 AI 代理技能和工作流程,帮助开发者理解不熟悉的代码库、评估变更影响,并成长为自信的维护者。

仓库上手教练 是什么?

该技能为 AI 代理(如 Claude Code、Cursor)提供了一套结构化的工作流程,用于帮助开发者深入理解并安全地维护任何代码仓库。它通过明确的模式(如 bootstrap、learn、change-prep)引导代理根据任务选择最合适的操作路径。核心是建立一个基于证据的模型,将关于代码库的声明分类为“已验证(Verified)”、“推断(Inferred)”或“未知(Unknown)”,从而管理不确定性。该技能强调创建一个持久的心智模型,而非生成大量的文档,并提供了一系列工具(如项目地图、变更摘要和竞争力评估)来支持从新手到自信维护者的成长。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add LM20230311/repo-confidence

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

仓库上手教练 是做什么的?

为当前仓库构建持久的心智模型和基于证据的维护系统。优化目标为人类理解、安全变更所有权和校准后的信心——而非最大文档量。

匹配用户的语言

用用户使用的语言编写解释和生成的产物。当用户使用中文时,默认使用简体中文。保持代码符号、路径、API名称和命令不变。当使用中文时,将证据标签渲染为 已验证(Verified)、推断(Inferred) 和 未知(Unknown)。

选择一种模式

选择能满足请求的最小模式:

模式使用时主要输出
ambient正常的 AI 辅助工作应继续,无需新流程简洁的影响、风险和验证上下文
bootstrap仓库或团队不熟悉项目地图 (Project Atlas)
learn用户希望理解某个领域或流程流程卡片 + 反向教学
change-prep某个需求可能导致代码变更变更摘要
refreshAtlas 已存在且代码已变更增量证据刷新
readiness用户想知道他们可以安全维护什么能力评估

对于普通需求,默认使用 ambient。当用户明确要求 bootstrap、learn、refresh 或 readiness 的输出结果,或者仓库本身就是任务时,使用这些模式。仅在用户明确需要时组合模式。对于狭隘的代码问题,不要生成完整的 Atlas。

与现有工作流程并行

在 ambient 模式下:

  1. 仅分析需求的可能路径和邻近风险。
  2. 除非用户要求,否则不要创建 Atlas 文件、安装钩子、更改 CI 或引入表单。
  3. 在编辑之前,当确实有帮助时,最多分享一个关于受影响的流程、状态/缓存影响、风险和预期验证的紧凑摘要。
  4. 继续进行低风险和可逆的工作,无需暂停等待反向教学或文档批准。
  5. 仅当缺失的决定会改变安全性、计费、破坏性数据行为、兼容性或其他高影响的不变量时,才暂停。
  6. 编辑后,比较预期影响和实际影响,运行适当的检查,并报告意外范围或未解决的风险。
  7. 除非用户明确请求学习或就绪性辅导,否则不要测试用户。

将信心视为交付的辅助工具,而非替代工作流程。

从仓库证据开始

  1. 读取所有适用的仓库指令,例如 AGENTS.md、CONTRIBUTING.md 和本地策略文件。
  2. 检查 Git 状态、当前分支、HEAD、仓库根目录和最近历史。保留用户更改。
  3. 当 Python 3 可用时,运行 scripts/repo_inventory.py <repo> 进行确定性的结构清单。
  4. 如果 .codegraph/ 存在,在 grep 或手动文件读取之前使用 CodeGraph 定位符号和关键路径。
  5. 检查实际的入口点、路由或作业注册、持久化模型、迁移、缓存、外部客户端、配置和测试。
  6. 优先使用当前代码和可执行的测试,而非过时的文档。必要时使用 Git 历史来解释不明显的决定。
  7. 切勿在生成的产物中暴露凭证、私有客户数据、生产秘钥或敏感的仓库内容。

应用证据模型

对重要声明进行分类:

  • 已验证 (Verified):直接由当前代码、测试、模式、配置或观察到的输出支持。
  • 推断 (Inferred):根据现有证据合理但未完全证实。
  • 未知 (Unknown):证据缺失、冲突、无法获取或需要运行时确认。

对于每个高影响声明,记录:

  • 声明;
  • 状态;
  • 源符号或文件;
  • 可用的支持测试或迁移;
  • 已验证的 Git 提交;
  • 过时或错误时的风险。

不要用流利的散文掩盖不确定性。将不确定性转化为明确的已知-未知项。

创建或刷新 Atlas 时,阅读 references/atlas-schema.md。在分析具体变更前,阅读 references/change-brief.md。在辅导或评估开发者前,阅读 references/competency-rubric.md。

引导项目地图 (Bootstrap a Project Atlas)

1. 建立项目护照 (Establish the project passport)

识别:

  • 目的和用户;
  • 语言、框架、构建工具和部署形态;
  • 可执行入口点和后台工作进程;
  • 主要数据存储、缓存、队列和外部服务;
  • 构建、测试、lint 和运行命令;
  • 仓库策略和操作约束。

2. 构建领域地图 (Build the domain map)

识别能解释系统的最小稳定词汇表:

  • 核心业务实体;
  • 模块之间的所有权边界;
  • 每个实体的真实来源;
  • 公共和内部接口;
  • 生命周期和状态转换。

不要逐个文件进行总结。按责任和业务能力对代码进行分组。

3. 选择关键流程 (Select critical flows)

使用以下标准对流程候选进行排名:

  • 业务中心性;
  • 请求或事件频率;
  • 状态突变;
  • 安全或财务影响;
  • 操作事件可能性;
  • 跨模块复杂性。

首先记录五到八个流程。仅在核心心智模型稳定后扩展。

对于每个流程,涵盖:

  • 触发器和入口点;
  • 身份验证和验证;
  • 编排和依赖项;
  • 读取、写入、事务和缓存行为;
  • 外部调用;
  • 失败、重试、回退、补偿和幂等性;
  • 授权、计费、审计和可观测性影响;
  • 不变量、测试、变更热点和已知未知项。

4. 创建风险和状态地图 (Create risk and state maps)

显式映射:

  • 数据库表和迁移;
  • 缓存键、TTL、预热和失效;
  • 队列、事件、锁和异步结算;
  • 外部提供商凭据和重新加载行为;
  • 安全性、隐私、计费、并发性、兼容性和迁移风险。

5. 编写 Atlas (Write the Atlas)

使用 assets/project-atlas-template/ 中的模板。仅复制仓库所需的部分。当用户授权编写文档且仓库没有首选位置时,默认位置为 docs/project-atlas/。

在关键页面上记录仓库相对的 Evidence paths 元数据,以便新鲜度检查可以映射 Git 更改而无需猜测依赖项。

保持索引简洁。使用渐进式披露:首先概述,其次是详细的流程和实体页面,最后按需进行精确的代码检索。

教学某个领域或流程

解释 (Explain)

从一屏心智模型开始,然后展示正常路径、失败路径和状态变更。解释设计存在的原因,而不仅仅是哪些函数调用彼此。

验证 (Verify)

对照测试、迁移、配置以及至少一个调用者或消费者交叉检查流程。显式标记差距。

反向教学 (Teach back)

当用户请求学习或辅导时,要求他们在不查看源代码的情况下解释流程。专注于因果性问题:

  • 什么触发了该流程?
  • 哪个状态是权威的?
  • 什么被缓存了,它如何变得过时?
  • 什么可能失败、重试、补偿或部分成功?
  • 破坏哪个不变量最危险?
  • 你将如何证明一个变更是安全的?

用具体证据纠正误解。避免关于行号或私有辅助函数名称的琐事。

模拟 (Simulate)

给出一个实际需求和一个失败场景。要求学习者预测受影响的模块、状态变更、测试、可观测性和回滚。将预测与仓库证据进行比较。

准备变更

使用 references/change-brief.md 中的模板。

在编辑之前,确定:

  • 用户意图和验收标准;
  • 明确假设;
  • 入口点和受影响的调用路径;
  • 数据模型、迁移、缓存、队列和外部服务影响;
  • 身份验证、授权、计费、隐私、并发性和兼容性影响;
  • 正常、失败、重试、回退和回滚行为;
  • 窄范围和广范围的验证命令;
  • 可观测性和发布计划;
  • 未解决的问题和风险评级。

在正常交付模式下,分享简洁的影响摘要并在范围内继续实施。在明确请求的学习模式下,在变更摘要后暂停,以便学习者在代码变更开始前预测实施。

实施后:

  1. 将实际差异与预期影响进行比较。
  2. 解释意外文件或行为。
  3. 运行适当的测试并检查结果状态。
  4. 仅更新其稳定知识已更改的 Atlas 页面。
  5. 添加新发现的未知项或不变量。

刷新现有 Atlas

  1. 运行 scripts/atlas_freshness.py <repo> --atlas <atlas-path> --format json 以获取确定性候选报告。
  2. 读取 Atlas 验证提交和声明的证据路径。
  3. 使用 Git diff、CodeGraph(当可用时)和历史记录将候选页面与当前 HEAD 进行比较。
  4. 将更改的文件和符号映射到受影响的流程、实体、状态图和不变量。
  5. 根据当前代码和测试重新验证受影响的声明。
  6. 保持不受影响的页面不变。
  7. 仅在检查证据后更新验证元数据。
  8. 报告可能过时但无法验证的页面。

将脚本的 review 状态视为提示进行人/AI 验证,而不是页面错误的证明。不要为了视觉一致性重写整个 Atlas。

评估维护就绪性

使用 references/competency-rubric.md,评估可观察行为而非信心声明。

评估开发者是否能:

  • 解释项目及其边界;
  • 跟踪核心流程;
  • 识别真实来源和缓存行为;
  • 预测变更影响;
  • 识别高风险不变量;
  • 设计测试、发布观察和回滚;
  • 完成并解释一个实际的范围变更。

报告:

  • 按领域划分的当前水平;
  • 已验证的优势;
  • 不安全或未经验证的领域;
  • 下一个最小的实际任务,该任务能产生成长的证据。

不要仅基于阅读或测验表现就声称开发者已准备好进行高风险维护。

保持人在决策环中

将 AI 用于发现、交叉引用、起草和实施。在决策边界处需要人类理解:

  • 接受高影响假设;
  • 更改不变量;
  • 批准迁移或兼容性中断;
  • 更改身份验证、计费、权限或破坏性行为;
  • 选择发布和回滚策略。

目标不是让人类匹配 AI 的检索速度。目标是让人类对系统有足够的理解,以判断、验证并拥有结果。

避免这些失败模式

  • 不要生成逐个文件的详尽百科全书。
  • 不要将调用图视为完整的业务解释。
  • 不要将推断的行为标记为已验证。
  • 在验证顶层流程之前,不要生成数百页。
  • 不要用名称而非因果推理来测试学习者。
  • 不要让文档阻碍紧急的安全交付,除非用户启用了培训模式。
  • 不要让 Atlas 生成修改应用代码。
  • 不要在清单输出或文档中暴露秘钥。
  • 不要承诺完全理解;要限定并跟踪不确定性。

资源路由

  • 运行 scripts/repo_inventory.py 获取只读的结构快照。
  • 运行 scripts/atlas_freshness.py 将 Atlas 验证提交和声明的证据路径与当前 Git HEAD 进行比较。
  • 阅读 references/atlas-schema.md 了解 Atlas 结构、证据标题和流程选择。
  • 阅读 references/change-brief.md 进行变更影响分析。
  • 阅读 references/competency-rubric.md 进行反向教学和就绪性评估。
  • 创建仓库文档时,从 assets/project-atlas-template/ 复制。

相关技能