代码风格一致性 Skill

核心目标

让每一行新生成的代码，读起来像是原项目的作者自己写的。

生成代码前先建立"风格基准"，再按基准约束输出——拒绝使用自己默认喜好覆盖项目已有约定。

工作流程：三步法

Step 1：建立风格基准（Style Fingerprint）

如果用户提供了项目路径，立即运行扫描脚本：

python3 ~/.workbuddy/skills/code-style-consistency/scripts/scan_style.py <项目根目录>

脚本自动识别：

• 技术栈（框架 / UI 组件库 / 状态管理 / 样式方案 / 构建工具）
• 命名约定（文件 / 组件 / 函数命名风格）
• Import 路径风格（@/ 别名 vs 相对路径）
• 组件写法（Function Component vs Class，Props 定义方式）
• 已使用的 UI 组件清单（Top 30）
• 异步请求模式（axios 封装 / React Query / SWR）
• 错误处理模式
• 代码规范配置（ESLint / Prettier / TypeScript strict）

如果用户没有提供项目路径，或需要补充机器无法识别的约定，参考 references/style-probe-questions.md 提问，最多问 5 个最重要的问题：

> 推荐优先确认的 5 项（快速最小集）：

> 1. 组件写法（FC / Hooks / Class）

> 2. 样式方案（Tailwind / CSS Modules / styled-components）

> 3. 请求封装位置（src/api/ 还是直接 axios）

> 4. Props 类型定义方式（interface 还是 type）

> 5. Import 路径风格（@/ 还是 ../）

建立风格基准的最快途径：要求用户提供代表性参考文件。 参考 references/representative-code-guide.md 指导用户找到高价值参考文件（最频繁被引用的组件、最近修改的页面、API 层封装文件）。

Step 2：理解需求，规划实现路径

在风格基准确定后，分析需求：

1. 定位需求类型
• 新增独立功能 → 新建文件，按项目目录结构约定放置
• 修改已有功能 → 先读懂原文件再修改，不引入新的写法
• 新增组件 → 对标项目里同层级组件的写法
• 新增 API 接口 → 对标 api/ 或 services/ 里的现有函数写法

1. 定位参考文件
• 在项目里找到最相似的已有实现作为参考
• 优先读参考文件再开始写，不要凭记忆/猜测

1. 规划文件清单
• 要新建哪些文件？放在哪个目录？
• 要修改哪些文件？
• 是否需要导出到 index 文件？

Step 3：一致性约束代码生成

生成代码时，严格遵守风格基准。每写一个代码块，内心过一遍 references/pre-generation-checklist.md 的快速自检口诀：

看样式，看导入，看命名，看类型
看请求，看状态，看弹窗，看提示
看导出，看文件，看结构，再出去

强制约束规则（不可违背）：

特殊场景处理

场景 A：用户提供参考文件（最高置信度）

用户说："参考这个文件帮我实现 XXX"——这是最理想的情形。

1. 仔细阅读参考文件，提取：import 结构 / Props 定义 / 组件骨架 / 导出方式 / 样式写法
2. 完全镜像参考文件的结构，只替换业务逻辑
3. 明确告诉用户"我将参考 [文件名] 的风格实现"

场景 B：修改已有文件

1. 先完整读取目标文件
2. 识别该文件的局部风格约定（可能与全局约定略有不同）
3. 修改时保持与该文件的局部风格一致，不要用其他文件的写法"污染"这个文件
4. 尽量做最小改动，不要顺手重构无关代码

场景 C：全新功能无参考文件

1. 从 scan_style.py 报告或用户回答中提取风格基准
2. 找到最近似的已有文件（同类型组件/页面/服务）
3. 先把该文件的骨架结构拿来，清空业务逻辑，按新需求填充

场景 D：用户风格基准不清晰，且无项目路径

直接问以下问题（不要超过 3 个，选最关键的）：

> "为了让生成的代码和你的项目风格一致，我需要确认几个关键点：

> 1. 项目用什么 UI 组件库？（比如 Ant Design / MUI / Element Plus）

> 2. 样式方案是 Tailwind、CSS Modules 还是 styled-components？

> 3. 可以提供一个项目里类似功能的现有组件文件给我参考吗？"

输出规范

代码输出时

• 开头说明参考了哪个文件/建立了什么风格基准
• 如果有任何不得不偏离项目风格的地方，显式标注并说明原因
• 代码块标注文件路径（// src/components/ProductCard/index.tsx）

风格基准报告（当需要时）

## 风格基准确认

**技术栈**：React 18 + TypeScript + Ant Design 5 + Tailwind CSS
**组件写法**：Function Component + Hooks（useState / useEffect / 自定义 hook）
**Props 定义**：`interface Props`（TypeScript strict 模式开启）
**样式方案**：Tailwind CSS，使用 `cn()` 合并条件类（tailwind-merge + clsx）
**Import 路径**：`@/` 别名（`@/components/`, `@/api/`, `@/hooks/`）
**请求封装**：`src/api/xxx.ts` → 调用 `src/utils/request.ts` 统一封装
**状态管理**：Zustand（全局）+ useState（本地）
**错误处理**：全局拦截器 + 业务层 `message.error()` 提示
**命名约定**：文件 PascalCase，函数 camelCase，API 函数前缀 get/create/update/delete
**注释语言**：中文注释为主

*以上基准来自：package.json + src/components/UserCard/index.tsx（参考文件）*

参考资源

• scripts/scan_style.py — 代码风格指纹自动扫描脚本（Step 1 首要工具）
• references/style-probe-questions.md — 风格探针问题清单（人工补充基准用）
• references/pre-generation-checklist.md — 代码输出前的一致性检查清单
• references/representative-code-guide.md — 如何找到项目最有代表性的参考文件

踩坑记录

> 实际使用中积累，格式：场景：经验要点

• Tailwind 项目：注意检查是否用 cn() 工具，很多项目引入了 tailwind-merge + clsx 封装的 cn()，不用这个就会破坏原有样式优先级逻辑
• Ant Design v4 vs v5：导入路径有变化（v5 用 antd，v4 某些组件从 @ant-design/icons 单独引入），混用会报错
• 别名路径：扫描脚本能检测 @/ 前缀，但无法确认别名是否在 tsconfig/vite.config 里实际配置了，修改前确认别名有效
• CSS Modules：部分项目 styles 对象 import 名不叫 styles，读文件时确认实际命名再使用