repo-skillopt

RepoSkillOpt — Canonical Skill

用途

这项技能通过基于证据的分析和由人工反馈驱动的迭代，帮助编码 Agent 理解遗留代码仓库。它会生成结构化的代码仓库规范，将人工修正作为一等输入，并支持一个有界循环：将反复出现的反馈汇总为可供审查的技能自身修改建议。这项技能与供应商无关，不依赖任何特定的编码 Agent 运行时。

触发条件

当用户要求理解、梳理、记录、熟悉、重构、修改或评估某个代码仓库，或使用这些动词的常见近义表达（例如：“解释这个代码库”“总结架构”“如果我们……会有什么变化”“这样做安全吗？”）时，启用这项技能。

如果请求不属于上述动词所涵盖的范围（例如，一般聊天、无关的写作任务、不需要理解整个代码仓库的单文件编辑），不要启用这项技能。此时继续执行常规 Agent 行为。

操作原则

• 不要只依赖 README 文件。 README 内容是证据，但并非全部事实。它们可能已经过时、只是设想，或并不准确。务必对照代码、配置、测试和命令输出加以佐证。
• 所有重要主张都必须以代码仓库中的证据为依据。 相较于泛泛的描述，应优先提供具体路径、符号、配置、测试和命令输出。重要主张是指填充代码仓库规范某个章节中非琐碎信息的任何断言（入口身份、技术选型、依赖关系、控制流或数据流步骤、集成目标、风险陈述），以及维护者读者可能据此采取行动的任何独立断言。对简单事实的复述（字面文件内容、原始配置转储、语法层面的改述）不属于重要主张。
• 将已验证的事实与假设区分开。 每项重要主张都必须恰好带有以下四种标签之一（定义见下文的输出规范）：**[fact]**、**[inference]**、**[unknown]**、**[human]**。
• 明确指出不确定性。 如果无法通过检查确定相关信息，应将这一缺口记录在未知项和未解决问题下，而不是猜测。坦诚地标为“未知”，比自信地给出错误答案更有用。
• 优先采用具体证据，而非基于训练数据进行模式匹配。 同一生态系统中的两个代码仓库也可能存在模式匹配无法发现的差异。请检查当前代码仓库。
• 不要仅凭浅层检查就夸大架构结论。 如果你只阅读了清单文件和少数入口文件，就不要把各层结构和数据流描述得仿佛已经追踪验证过。
• 只有在范围界定恰当时，才将人工反馈保留为可复用知识。 特定于某个代码仓库的事实应限定在该仓库的范围内；只有明确标记为可作为通用候选的反馈，才会进入以技能自身为目标的收敛流程，而且即使如此，也只能通过已接受的技能修改提案进行处理。

仓库理解工作流

按顺序执行以下阶段。跳过或调整阶段顺序会削弱后续部分所依赖的证据链。

(a) 梳理仓库结构。 列出顶层目录。注意是否存在 src/、测试、文档、部署文件、CI 配置、多个子项目（单体仓库信号）。

(b) 识别语言、框架、包管理器和运行时。 阅读清单文件（pyproject.toml、package.json、go.mod、pom.xml、Cargo.toml、Gemfile、composer.json 等）。记录版本和运行时约束。

(c) 检查清单文件、配置、测试、部署文件和入口点。 至少阅读：构建／运行时配置、环境模板、CI 工作流定义、测试运行器配置、部署清单文件，以及识别出的入口点文件（CLI 脚本、HTTP 路由注册、库的 __init__／index 文件）。

(d) 梳理模块、层级、依赖、领域概念和数据流。 遍历源代码树；为每个模块分配职责；识别各层之间的依赖方向；记录该代码库中的领域专家使用的术语。枚举仓库中定义的每个函数和类，避免遗漏任何符号（请参阅 仓库规范格式 下的符号核对规则）。

(e) 从入口点追踪特定行为，直至核心逻辑和持久化或副作用。 至少针对一个与用户相关的行为，生成编号追踪，列出每一跳（入口点 → 中间件 → 服务 → 仓库 → 副作用／存储），并在每一跳标注文件和符号。

(f) 逐步生成仓库规范，并写入磁盘。 使用 templates/repository-specification.md 中的仓库规范模板，填写全部 19 个必需章节，并遵循 输出规范 中的标签和引用要求。完成每个章节后，立即将其写入规范文件，不要在工作上下文中保留已写入的章节——章节持久化后，将其从工作集里移除，只保留当前正在编写的章节及其所需证据。如果后续章节需要查阅先前章节（例如，为 证据索引 去重），应从文件中重新读取，而不是在上下文中保留整份文档。这样可以让工作上下文仅限于当前章节，而不是不断增长的整份规范，使工作流能在较小的上下文窗口中处理大型仓库。磁盘上的文件始终是权威规范，而不是上下文中的副本。

(g) 识别风险、未知事项和安全的后续步骤。 在 已知风险 中填写特定于该仓库的风险（而非泛泛的风险），并为每项风险提供证据。在 未知事项和未解决的问题 中列出阶段 (a)–(f) 中发现的所有缺口。建议人类采取具体的后续步骤，以解决关键未知事项。

(h) 确保符号完整性（确定性——最后一步）。 在结束前，确保 尚未分析的符号 列表完整且通过机械方式生成：所有尚未讨论的函数和类都必须按文件分组列出，并附上计数行。应通过运行一个完整性辅助工具来确定性地生成此列表：该工具枚举仓库中的符号，并列出分析中未提及的符号；不要手动抄录。你的工作是进行上述分析；这一步负责确保核对完整，避免遗漏任何内容。

仓库规范格式

仓库规范模板位于 templates/repository-specification.md。Agent 必须生成符合该模板的文件，包含按以下顺序排列的全部 19 个章节：

1. 仓库概览
2. 技术栈
3. 构建和运行命令
4. 主要入口点
5. 架构分层
6. 核心模块
7. 领域模型
8. 数据模型
9. 外部集成
10. 控制流追踪
11. 数据流追踪
12. 依赖关系图
13. 配置映射
14. 测试策略
15. 部署假设
16. 变更影响图
17. 已知风险
18. 未知事项和未解决的问题
19. 证据索引

对于有意留空的部分，必须明确写出“已知项为无”或“不适用”，不得直接省略。证据索引列出文档中出现的每条不同引用，并去重。

符号统计（不得悄然省略）。 必须统计仓库中定义的每个函数和类：要么在分析结论或引用中提及，要么列在核心模块的**“尚未分析的符号”**小节中（按文件分组；对于大型仓库，可列出每个文件的计数）。注明数量——定义 N 个，已分析 M 个，列出 N−M 个——让读者确认没有内容被隐藏。排除生成目录和 vendored 目录。

仓库本体（先构建）。 在编写领域模型和数据模型之前，先构建仓库本体：盘点固定类型的实体——模块、类、函数、数据实体、路由、作业、抽象——并为每个实体标注 file:line；盘点实体间的关系——导入、继承、外键、注册路由、调度。使用快速扫描器定位它们（可用时使用 rg，否则使用 grep/git ls-files），并且只读取要引用的匹配行——不要加载整个文件。在领域模型中提供高层次的实体映射表（类型 · 数量 · 带引用的示例）和关系 graph。抽象实体必须通过结构识别——即被两个或更多其他类继承的基类——而不是依据固定的、针对特定仓库的名称列表。关系的目标如果无法解析为已知实体，则标记为 **[inference]**/**[unknown]**，且不得将其绘制为确定的边。

数据模型图。 如果仓库包含数据库或持久化架构，数据模型部分必须包含一个围栏代码块 ```mermaid，其中绘制真实表/模型的 erDiagram，标出其关键列和外键关系，并确保每个实体都可追溯到定义它的架构文件（迁移文件、DDL 或 ORM 模型）。此 erDiagram 是本体中的数据实体部分。如果没有持久化架构，则写明“不适用”；不得绘制虚构的架构。

业务工作流（涵盖每条业务流水线）。 在业务工作流中，完整列出每个业务入口点——HTTP 路由、定时作业、CLI 命令——不得悄然省略：在枚举表中注明各类型的数量和总数，并为每个入口点标注 file:line。随后沿仓库本体追踪每个入口点的操作流程——入口点 → 服务调用 → 副作用/持久化。使用快速扫描器（rg/grep）定位入口点，并且只读取匹配的处理函数代码段。每条流程都以 mermaid flowchart 开始（仅作可视化；不带引用），随后给出权威的、带引用的编号步骤。无法静态解析的跳转（动态分派、间接调用）必须标记为 **[unknown]** 并说明原因，不得省略。这是与控制流追踪部分相对应的业务流程内容：追踪仅作示例；此处则要求穷举。

呈现格式。 规格说明面向读者，因此应优先采用便于快速浏览的结构：

• 按模板顺序使用带编号的章节标题——## 1. Repository overview … ## 19. Evidence index。
• 将本质上属于表格的章节呈现为 Markdown 表格，并包含 Evidence 列（path:line 引用）和 Label 列（[fact]/[inference]/[unknown]）：Technology stack、Dependency map、Configuration map、Data model 的字段列表，以及 Evidence index。
• 对于 Control-flow traces 和 Data-flow traces，先用围栏代码块 ```mermaid 绘制一个端到端展示步骤的 flowchart，然后在其下方列出带标签且附有引用的权威编号步骤。
• 图表（flowchart、erDiagram）是视觉辅助，不带任何引用；图表展示的每个步骤或实体也必须出现在带标签且附有引用的行或表格行中，以确保图表的证据依据不受影响。

规范标题与质量检查清单。 在标题下方，附上简短的标题信息块——Target repository（名称 · commit）、Status、Generated by（技能版本 · adapter），以及 Grounding 行，与结构化规范惯例保持一致。除 Repository Specification 外，还要根据 .reposkillopt/specs/repository-specification-checklist.md 中的 templates/repository-specification-checklist.md 生成一份 Specification Quality Checklist：包含覆盖证据依据、完整性、图表和就绪状态的 CHK### 检查项。其证据依据、完整性和图表检查项应对应确定性指标，因此，全绿的检查清单应与 100% 的引用依据率、章节完整率、符号覆盖率和图表依据率相符。

此技能生成的工作产物存放在目标仓库根目录（正在分析的仓库，而非分发此技能的项目）下的 .reposkillopt/ 目录中，固定子目录如下：

• .reposkillopt/specs/ — Repository Specifications
• .reposkillopt/feedback/ — Feedback Items
• .reposkillopt/rollouts/ — Rollout Logs
• .reposkillopt/proposals/ — Skill Edit Proposals

人工反馈循环

Human Feedback 模板位于 templates/human-feedback.md。Rollout Log 模板位于 templates/rollout-log.md。

当人工针对 Repository Specification 提供反馈时：

1. 先记录反馈，再应用。 使用模板，将 Feedback Item 写入 .reposkillopt/feedback/FB-YYYY-MM-DD-NNN-<slug>.md。指定十一种 type 值之一（correction、confirmation、missing-context、terminology、quality-rating、avoid-path、deeper-analysis、criticism-of-claim、format、detail-level、cross-agent-difference）。指定 scope：对于特定于此代码库的事实，使用 repository-scoped；对于可能需要在未来修改此技能的模式，使用 candidate-for-generic。

2. 修订当前的 Repository Specification。 应用反馈。对于已更改的 **[fact]** 声明，更新引用。对于已被取代的声明，在原处标记为已取代；不得悄悄改写历史。增加规范的 revision，更新 revised，并在规范的 Change log 附录中追加一行，列出已应用的 Feedback Item id。

3. 更新本次会话的 Rollout Log。 在 Human feedback received this session 下列出 Feedback Item id，并为每项标注 (applied)、(deferred) 或 (withdrawn)。在 Revisions applied 下列出已修订的规范章节。

4. 不得悄悄将特定于仓库的事实提升为此规范技能的内容。 标记为 scope: repository-scoped 的反馈仅保留在目标仓库的产物中。只有通过下文的 Skill Convergence Loop 生成并获接受的 Skill Edit Proposal，才能将其提升为规范内容。

人工反馈同时用于两方面：立即改进当前的 Repository Specification，以及为技能趋同提供长期输入。

技能收敛循环

技能编辑提案模板位于 templates/skill-edit-proposal.md。

当反复出现的反馈（通常是在一个或多个会话中出现三个或更多相关反馈项）表明该技能本身存在弱点时：

1. 总结模式。 找出支撑反馈项中反复出现的特征。确认该模式可以泛化（有助于处理其他代码仓库或任务），而非当前代码库中的一次性细节。

2. 提出一个或多个范围明确的编辑。 每项提案都是一个单独的接受或拒绝单元，规模要小到审阅者能在五分钟或更短时间内作出决定（review_time_estimate_minutes ≤ 5）。如果提案不符合这一要求，就拆分它。

3. 为每项提案分类。 使用六种 edit_kind 值之一：

   • ADD — 添加新内容
   • REPLACE — 替换现有内容
   • DELETE — 删除内容
   • REORDER — 更改现有内容的顺序
   • SPECIALIZE — 限定现有规则的适用范围（更具体的情况）
   • GENERALIZE — 扩大现有规则的适用范围（涵盖更多情况）

4. 标记范围。 只有 scope: generic 才符合纳入规范版本的条件。scope: repository-scoped 提案必须改写为可泛化的提案、予以拒绝，或转交给每个代码仓库的范围决策产物。

5. 保留被拒绝的提案。 将 status 设为 rejected，并填写 decision_rationale。不要删除它们——被拒绝的提案属于审计记录的一部分。

6. 接受前通过关卡验证。 scope: generic 提案只有在通过验证关卡后才能将 status 改为 accepted：将其应用于候选技能版本后，必须针对一个留出的参考集重新生成规范说明。该参考集必须与促使提出该提案的代码仓库互不重叠；其各维度量规评分不得退步，确定性检查也必须仍然通过；同时，提案预期产生的效果至少要体现在一个维度上（或明确豁免）。本次运行须记录为验证关卡报告，并由提案引用。该关卡授权接受提案，但不能取代下方的接受流程。

7. 将已接受的提案应用于规范技能。 当 status 为 accepted（并引用通过的关卡报告）时，将提案中的差异应用到此 SKILL.md。按照 Keep-A-Changelog 和 semver 递增规范版本：如果差异破坏适配器等效性检查清单，则递增 major；如果是新增内容，则递增 minor；如果是澄清内容，则递增 patch。在 skills/repo-skillopt/CHANGELOG.md 中添加一行。

8. 优先选择可泛化的编辑。 如果拟议的更改会使通用技能针对单个代码仓库进行特化，则标记或改写该提案。对于此产物，可泛化的改进比代码仓库特定的改进更重要。

输出规范

Repository Specification（或任何 rollout 产出的文本）中的每项重要声明，都必须且只能带有以下四种标签前缀之一，且标签须置于声明之前：

• **[fact]** — 已通过检查验证。必须紧接至少一条以下格式的引用：
  • path/to/file.ext:line
  • path/to/file.ext:start-end
  • path/to/file.ext:Symbol
  • path/to/file.ext:Symbol:line
  • cmd: <command>，后接 output: <verbatim output>
• **[inference]** — 根据部分线索推导得出。说明依据（例如，“依据：src/auth.py:7 中存在 flask_login 导入”）。
• **[unknown]** — 明确标记为尚未确定。也须出现在 Unknowns and unresolved questions 下，或由其引用。
• **[human]** — 由反馈循环中的人员提供。引用来源反馈项 ID（格式：FB-YYYY-MM-DD-NNN）。

将假设表述为事实属于缺陷。事实缺少引用属于缺陷。无法验证的声明既未标记为 **[inference]**，也未标记为 **[unknown]**，属于缺陷。输出应对真正的工程师有用——这意味着值得信赖，而非仅仅好看。

简单复述（文件内容原文、原始配置转储、语法上的改述）不属于重要声明，无需添加标签。