sunrain520/spec-first/spec-rule-miner

Spec Rule Miner

Purpose

spec-rule-miner 从目标仓库的真实代码中提炼项目级 AI 编码规则，把完整规则写入独立规则文件，并让 AGENTS.md / CLAUDE.md 这类 host 入口文件引用该文件。它是 standalone skill，不是 spec-* public workflow。

核心产物是 <=1000 words 的项目规则块，规则必须来自当前目标仓库证据，而不是语言默认、个人偏好或通用最佳实践。

When To Use

• 使用本 skill：用户要“分析项目风格”“学习代码规范”“生成项目规则”“挖掘编码习惯”“让 AI 像团队一样写代码”，或明确要生成 AGENTS.md/CLAUDE.md 引用入口、Cursor/Qoder 规则文件。

When Not To Use

• 不使用本 skill：用户要审查当前 diff、修复代码、重构、调试、写 lint/format 配置、生成通用语言规范，或治理 confirmed team policy。
• 近邻路由：confirmed team policy governance 已退役，不再提供专用入口；代码质量评审走 spec-code-review；实际实现或修复走 spec-work（bug 根因排查走 spec-debug）；创建或修改 spec-first source skill 走 spec-write-skill。命中近邻路由时必须在回复中点名目的地 skill（例如：「这是代码评审请求，属于 spec-code-review」）——只解释不匹配而不指路，owner 依然无路可走。点名之后不得在本会话内替目的地干活：直接修 bug、直接做代码评审、直接实现需求，都是把别的 workflow 的职责搬进 rule-miner 执行；用户的即时指令（「顺手修了」「直接审了」）不构成跨 workflow 代行授权——正确动作始终是点名目的地并交还路由。

Inputs

• target_repo：必须是一个明确的本地目标仓库。
• 当前仓库的人写源码、测试、配置和已有 agent rule 文件。
• 用户指定的输出目标；未指定时使用默认目标。

Outputs

• rules_block：写入独立规则文件的纯规则正文，使用 spec-rule-miner-start / spec-rule-miner-end markers。
• evidence_summary：每个规则组的代表性文件路径和样本限制；不写入规则文件，除非用户明确要求。
• target_files：默认独立规则文件、入口 pointer 文件与用户指定输出文件，说明 pointer 还是 inline。
• limitations：小样本、大仓库/多包抽样、混合语言、生成代码占比高、历史例外、冲突模式跳过、图候选未回源、refresh no-op、headless 默认写入等限制。

Hard Boundaries

• 只读目标仓库代码；不要修改业务源码、测试、构建配置或 formatter/linter 配置。
• Host-projected copies are outside this skill's rule targets；具体禁区见 Write Targets。宿主投影过期时从 source 运行 spec-first init 修复。
• 写入独立规则文件和引用入口前必须 preview 规则正文和目标文件；交互可用时等待用户确认。只有用户明确要求直接写入，或宿主/调用参数明确证明当前运行是 headless/non-interactive，才使用默认目标；普通聊天里用户暂未回复不能算 headless。默认写入必须在 closeout 记录 headless_default_write、目标文件和限制。
• 不覆盖用户已有规则。读取目标文件后，只替换 spec-rule-miner markers 内的旧块；无 markers 时追加；疑似旧版无 marker 输出时先询问替换还是追加。
• 非首次执行必须先重新取证并生成 candidate rules block，再与现有 canonical marked block / pointer 对比；无实质变化时不重写文件，closeout 记录 refresh_noop、采样范围和限制；有变化时 preview diff 后只替换 marker 内内容。
• 每条规则必须有当前仓库证据：默认至少 2 个文件支撑；小仓库样本不足时降级说明 sample-size；不确定或 50/50 分裂的模式不写成规则。
• 不泄露敏感信息：密钥、内部 URL、私有包名、账号、生产路径、安全实现细节只用于判断，不进入规则正文。

Workflow

1. 明确 target_repo。父级多仓工作区必须先锁定一个目标仓库；不清楚时只问一个问题。
2. 盘点仓库形态：根目录、主要语言、源码目录、测试目录、配置文件、包/应用边界、生成物/依赖目录和已有 agent rule 文件；多包 workspace 必须识别具体子项目范围。
3. 过滤读取范围：跳过依赖、构建产物、锁文件、minified 文件、二进制、vendored/generated 代码；大仓库或多包仓库使用分层抽样并在 preview 和 closeout 中披露样本包、未覆盖子项目和适用范围。
4. 读取并记录证据。抽取前先读 Pattern Categories，用其中类别组织证据；大仓库可按其中 capability-class 边界使用 code-graph / project-graph 候选缩小阅读范围，但规则证据必须回到当前源码；配置已强制的 formatter/linter 规则只记录为“已由工具处理”，不要重复写入 AI 规则。
5. 合成规则：按 frequency x deviation from defaults 排序，保留高频且偏离默认的做法；多包规则必须区分跨包通用模式、包级专属模式和历史例外，旧项目反例只能写成“新增代码优先”或“不扩大例外”；除非证据在适用范围内压倒性一致，不使用全仓库绝对措辞。必须包含至少一个 hidden association 和至少一个 anti-pattern，除非证据明确不存在，并在 preview 限制中说明。规则正文可以包含适用范围和例外边界，这不算挖掘过程元说明。
6. Preview：展示将写入独立规则文件的规则块、入口引用文件、word count、采样/证据限制、适用包范围、历史例外、refresh diff/no-op 判断，以及每个规则组的代表性 source refs。规则正文不要包含挖掘过程元说明。
7. 写入前读 Write Targets，按目标文件的 marker、frontmatter、pointer/inline 规则执行。默认把完整规则写入 docs/ai/project-rules.md，并让 AGENTS.md 与 CLAUDE.md 指向该文件。
8. 收尾输出：列出写入文件、规则字数、是否采样、未写入的近邻工具文件、需要用户手动检查的限制；如果没有写文件，说明 preview-only 状态；如果因 headless 走默认写入，必须说明 headless_default_write 的证据来源。

Failure Modes

• 目标仓库没有可分析源码：不生成空规则，说明需要先有代码样本。
• 用户请求 .cursorrules、.kiro/steering/**、GitHub Copilot、Trae 或其他未支持规则文件：说明目标不在当前支持范围内，不猜路径、不写 pointer。
• 旧版无 marker 规则块无法安全识别：先询问“迁移到独立规则文件还是追加 pointer”。
• 证据不足、模式冲突或生成代码占比过高：降级为 limitations，不把不确定模式写成规则。
• 重新挖掘后与现有 marked block 无实质变化：不要为更新时间戳、排序或同义改写而重写文件；输出 refresh_noop 和本次验证过的 source refs / limitations。

Quality Checks

• 规则块 <=1000 words；中文按连续中文字符粗略折算，宁可少写。
• 每条规则都能指向当前目标仓库证据；路径在文件树中真实存在。
• 规则只描述“当前项目如何做”，不提出重构建议，不评价团队好坏。
• 不把 language/framework 默认、formatter/linter 已强制项或生成代码习惯写成项目规则。
• 多包或混合框架仓库中，跨包规则只写稳定通用模式；包级规则必须带适用范围，并提示改具体子项目先跟随本包现有结构。
• 存在历史例外或旧项目反例时，用“新增代码优先沿用主模式”“不要扩大历史例外”这类收窄表达；不要写成“全仓库统一/只/永远/不得”的绝对事实。
• docs/ai/project-rules.md 是默认 canonical full rules；AGENTS.md、CLAUDE.md 和其他非 inline 工具文件默认只写 pointer。