inherit-legacy-style

用途

inherit-legacy-style 用于在遗留项目中防止 AI 生成代码发生风格漂移。它扫描代码库中的隐含约定，与使用者逐一解决冲突，并将共识固化为可执行的 .ai-style-rules.md 文件。该技能完全与语言和框架无关。

适用时机

用户输入 /inherit-legacy-style
用户提到要将 AI 接入手写的遗留项目
用户担心 AI 生成代码偏离现有项目约定
用户希望提取并编码项目的隐含编码规则

前置条件

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

工作流程

第 0 步 — 自动检测模式

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

不存在 → 分支 A（首次全量扫描）
存在 → 分支 B（增量嗅探）

用一行说明所处模式后继续，不询问用户选择。

分支 A — 首次全量扫描

测量规模并选择扫描层级

使用命令统计源文件数量（js、ts、jsx、tsx、vue、py、go、rs、java、kt、rb、php、cs、swift、c、cpp、h）。

小型：约 50 个以内，全部源文件逐一精读
中型：50–500，基础设施层全量读取，业务层每个维度抽样 2–3 个
大型：约 500 以上，严格抽样并设预算上限；先 --stat 摘要，再有针对性读取

沿 4 个维度扫描

文件解剖：文件内声明顺序（导入 → 类型 → 主逻辑 → 辅助函数 → 导出）
状态与控制流：异步状态、分页、标志位的命名约定
基础设施：跨领域工具的位置（拦截器、格式化器、中间件）
错误处理：try/catch 与全局拦截器与 Result 返回；空值检查习惯

应用信号阈值降噪

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

弱信号 → 自动抑制：少数派 <5% 且数量 <10 → 多数派胜出，少数派进入 DONTs
强信号 → 追问：接近均分，或在核心维度上存在语义分叉
小项目例外：源文件约 50 以内时，"3 对 2" 不算多数 → 需要追问

逐个解决冲突（追问协议）

对每个强信号冲突，只呈现一个问题，含 4 个选项：

证据：pathA 使用风格 X，pathB 使用风格 Y
警告：混用两者会割裂项目风格
选择：1 跟随 X，2 跟随 Y，3 这是演进，更新规则，4 我有新规则

暂停等待用户回答，然后进入下一个冲突。绝不堆叠多个问题。

生成 .ai-style-rules.md，包含三个必备章节：

[Golden Files] 真实范例路径，并注明其示范内容
[Naming & State-Control Rules] 具体、可检查的约定
[DONTs] 不得扩散的反模式

安装持久化钩子

询问用户执行强度：

选项 1 软钩子（推荐）：将 @.ai-style-rules.md 引用写入项目 CLAUDE.md
选项 2 硬钩子：软钩子 + settings.json 中的 PreToolUse[Write|Edit|MultiEdit] 钩子
选项 3 无钩子：保留规则文件，由用户手动引用

分支 B — 增量嗅探

读取现有 .ai-style-rules.md；若带有提交指纹，使用 git diff <last_hash> HEAD --stat 定位增量
读取近期 Git 变更（git log -3 --stat，按需检查可疑文件）
对超大差异（数百个文件以上）：仅看 --stat 摘要 + 抽样最大的变更
将新代码与已记录规则对比 → 冲突走追问协议
在 .ai-style-rules.md 末尾追加演进日志（绝不覆盖旧规则）

每轮强制

当 .ai-style-rules.md 通过 CLAUDE.md 加载进上下文时，每个写代码任务都必须在推理链开头给出合规声明，指明遵循的范例与规避的 DONTs。

输出规范

项目根目录下的 .ai-style-rules.md（头部含提交指纹 + 规模层级）
可选生成含 @.ai-style-rules.md 引用的 CLAUDE.md
演进日志以 ### [YYYY-MM-DD] Style Evolution Log 条目追加

反模式

不要跳过规模测量步骤：抽样 30 个文件的项目会"饿死"它；全量扫描 5000 个文件的仓库会失控
不要一次堆叠多个冲突问题：追问严格逐个进行
增量模式下不要覆盖旧规则：始终追加演进日志
未经询问不要默认使用"硬钩子"：执行强度由用户决定
不要评判语法或技术栈质量：该技能只对齐元架构
不要从范例文件复制 bug：复用结构，标记缺陷

最佳实践

扫描前用一行说明检测到的模式（首次 vs 增量）与规模层级
大型项目先读 --stat 摘要，再有针对性地读取可疑文件
让信号阈值处理噪声：843 对 8 的命名分布应自动解决，无需打断用户
对信号强度存疑时，倾向于询问
CLAUDE.md 软钩子（@.ai-style-rules.md）通常足够；仅当用户需要机械强制时才用硬钩子

示例

首次接入：用户说"帮我把 AI 接入这个较旧的代码库，但不要改变它的风格。" → 运行分支 A 全量扫描 → 测量规模 → 扫描 4 个维度 → 追问冲突 → 生成 .ai-style-rules.md → 提供钩子强度（软/硬/无）。

团队变更后的增量更新：用户说"我们新增了一个模块；保持现有风格规则不变。" → 运行分支 B 增量嗅探 → 将 Git 增量与已记录规则对比 → 追问任何新冲突 → 追加演进日志而不覆盖。

通过 CLAUDE.md 强制 DONTs：用户说"确保所有新代码与项目规则保持一致。" → 安装软钩子 → .ai-style-rules.md 每次会话自动加载 → 每个写代码任务开头给出合规声明，复用范例模式并规避 DONTs。

技能介绍

用途