inherit-legacy-style

Inherit Legacy Style

通过扫描代码库在 4 个元架构维度上的隐式约定、逐个与用户解决冲突，并把共识固化为可执行的 .ai-style-rules.md，防止 AI 在 legacy 项目中产生代码风格漂移。完全语言和框架无关。

何时激活

• 用户输入 /inherit-legacy-style
• 用户提到把 AI 接入手写 legacy 项目
• 用户担心 AI 生成代码偏离现有项目约定
• 用户想提取并编码项目的隐式编码规则

何时使用

当你需要保留 legacy 项目风格并防止 AI 生成代码漂移时使用。触发条件见上方 何时激活。

前置条件

• Git（推荐；非 Git 项目在增量模式下回退到文件时间戳）
• 项目根目录读/写权限（生成 .ai-style-rules.md，可选生成 CLAUDE.md）

工作流

Step 0 — 自动检测模式

静默检查项目根目录是否存在 .ai-style-rules.md：

文件存在？	模式
否	Branch A — 首次完整扫描
是	Branch B — 增量嗅探

用一句话宣布模式并继续——不要让用户选择。

Branch A — 首次完整扫描

1. 衡量规模，选择扫描层级

git ls-files | grep -cE '\.(js|ts|jsx|tsx|vue|py|go|rs|java|kt|rb|php|cs|swift|c|cpp|h)$'

层级	源文件数	策略
Small	≲ 50	完整细读每个源码文件
Medium	50–500	Infra layer = 全读；business layer = 每个维度采样 2–3 个
Large	≳ 500	严格采样 + 预算上限；先 --stat 摘要，再定向读取

2. 沿 4 个维度扫描

1. File Anatomy — 文件内声明顺序（imports → types → main logic → helpers → export）
2. State & Control Flow — async state、pagination、flags 的命名约定
3. Infrastructure — cross-cutting utils 放在哪里（interceptors、formatters、middleware）
4. Error Handling — try/catch vs global interceptor vs Result return；null-check 习惯

3. 应用信号阈值降噪

打断用户前，先评估信号强度：

• 弱信号 → 自动抑制：少数派 <5% 且 count <10 → 多数派获胜，少数派进入 DONTs
• 强信号 → 追问：接近平分，或核心维度上的语义分叉
• 小项目例外：sources ≲50 时，“3 vs 2”不是多数 → 追问

4. 逐个解决冲突（Grilling Protocol）

对每个强信号冲突，只提出一个带 4 个选项的问题：

Evidence: pathA uses style X, pathB uses style Y WARNING: Risk: mixing both fractures the project style Choose: 1 follow X 2 follow Y 3 this is evolution, update rules 4 I have a new rule

暂停直到用户回答，然后再处理下一个冲突。不要堆叠问题。

5. 生成 .ai-style-rules.md，包含三个必需 sections：

• [Golden Files] — 真实 exemplar paths，并注明它们展示什么
• [Naming & State-Control Rules] — 具体、可检查的约定
• [DONTs] — 不得传播的反模式

6. 安装持久 hook

询问用户 enforcement strength（使用 AskUserQuestion）：

选项	机制
1 Soft hook（推荐）	在项目 CLAUDE.md 写入 @.ai-style-rules.md 引用
2 Hard hook	Soft hook + settings.json 中的 PreToolUse[Write|Edit|MultiEdit] Hook
3 No hook	保留 rules file；用户手动引用

Branch B — 增量嗅探

1. 读取现有 .ai-style-rules.md；如果有 commit fingerprint，用 git diff <last_hash> HEAD --stat 定位 delta
2. 读取最近 Git 变更（git log -3 --stat → 按需检查可疑文件）
3. 对过大 diff（数百文件以上）：只看 --stat 摘要 + 采样最大变更
4. 将新代码与已记录规则比较 → 冲突走 Grilling Protocol
5. 在 .ai-style-rules.md 末尾追加 evolution log（不要覆盖旧规则）

每轮执行约束

当 .ai-style-rules.md 进入上下文（通过 CLAUDE.md 加载）时，每个写代码任务都必须在 reasoning chain 开头给出合规声明，说明遵循哪个 exemplar、避免哪些 DONTs。

工作方式

此技能通过 .ai-style-rules.md 是否存在，自动检测首次运行或增量运行：

• 首次（Branch A） — 衡量项目规模，跨 4 个元架构维度扫描代码库（File Anatomy、State & Control Flow、Infrastructure、Error Handling），用信号阈值降噪抑制弱冲突，与用户逐个解决强信号冲突，生成带 Golden Files / Naming Rules / DONTs 的 .ai-style-rules.md，并提供可选 enforcement hooks。
• 增量（Branch B） — 读取现有规则，检查最近 Git diff 中的新模式或冲突模式，对任何发现的冲突运行同样逐个追问协议，并追加 evolution logs，不覆盖现有规则。
• 每轮执行 — 通过 CLAUDE.md 挂接后，每个写代码任务都以合规声明开头，说明遵循的 exemplar 和避免的 DONTs。

输出规格

• 项目根目录的 .ai-style-rules.md（header 包含 commit fingerprint + scale tier）
• 可选带 @.ai-style-rules.md 引用的 CLAUDE.md
• 追加为 ### [YYYY-MM-DD] Style Evolution Log 条目的 evolution logs

反模式

• FAIL：不要跳过规模衡量步骤——对 30 文件项目采样会“饿死”它；对 5,000 文件 repo 全读会爆炸
• FAIL：不要一次堆叠多个冲突问题——grilling 严格逐个处理
• FAIL：增量模式不要覆盖旧规则——始终追加 evolution logs
• FAIL：不要默认 “hard hook” 而不询问——enforcement strength 由用户决定
• FAIL：不要评价语法或技术栈质量——此技能只对齐元架构
• FAIL：不要复制 exemplar files 中的 bug——复用结构，标记缺陷

最佳实践

• 扫描前用一句话宣布检测到的模式（首次 vs 增量）和规模层级
• 对大项目，先读 --stat 摘要，再对可疑文件定向 Read
• 让信号阈值处理噪声——843-vs-8 的命名分歧应自动解决，不打断用户
• 不确定信号强度时，倾向询问
• CLAUDE.md soft hook（@.ai-style-rules.md）通常足够；只有用户需要机械强制时才用 hard hook

相关技能

• init — 初始化带代码库文档的 CLAUDE.md
• code-review — 审查 diff 的正确性和风格问题
• simplify — 审查代码复用和简化机会

示例

1. 首次接入

   • User: “Help me onboard AI to this older codebase without changing its style.”
   • Action: 运行 Branch A 全扫描 → 衡量规模 → 扫描 4 个维度 → 追问冲突 → 生成 .ai-style-rules.md → 提供 hook 强度（soft/hard/none）。

2. 团队变更后的增量更新

   • User: “We added a new module; keep existing style rules intact.”
   • Action: 运行 Branch B incremental sniff → 将 Git deltas 与已记录规则比较 → 追问任何新冲突 → 追加 evolution log，不覆盖。

3. 通过 CLAUDE.md 强制 DONTs

   • User: “Make sure all new code stays consistent with the project's rules.”
   • Action: 安装 soft hook → 每个 session 自动加载 .ai-style-rules.md → 每个写代码任务以合规声明开头，复用 exemplar patterns 并避免 DONTs。