1. 项目概述当AI助手开始理解你的代码规范最近在团队里推广AI编程助手发现一个挺普遍的现象新同事用Claude或者Cursor写代码生成速度是快但代码风格五花八门有的用双引号有的用单引号缩进是两个空格还是四个空格全看AI当天心情更别提项目特有的目录结构、组件命名这些深层规范了。每次Code Review都得花大量时间纠正格式问题而不是聚焦在逻辑和架构上。这让我意识到仅仅让AI“写出能跑的代码”是远远不够的我们真正需要的是让它成为理解并遵守团队工程规范的“智能协作者”。这就是“Claude Code -8 Skills 实战指南”要解决的核心问题。这里的“Claude Code”并非指某个特定软件而是一种方法论和实践集合核心是利用Claude等大模型特别是其Code版本或相关技能的“Skills”技能机制将你团队的工程规范——包括代码风格、架构模式、安全规则、甚至评审要点——转化为AI可理解、可执行的指令集。而“-8 Skills”更像是一个代号代表一套经过精心设计和组合的、用于约束和引导AI编码行为的核心技能包。简单说就是教AI按你的规矩办事让它生成的代码从第一行起就是“可合并”的状态。这不仅仅是配置一个linter那么简单。它涉及如何将模糊的、基于经验的“好代码标准”结构化如何将这些标准有效地“注入”到AI的上下文窗口以及如何在不同的开发场景如新建文件、重构旧代码、修复Bug下动态调整AI的行为。对于前端、后端、移动端等不同技术栈的团队这套方法的实践细节各不相同但其思维模型是相通的将AI从“代码生成器”升级为“规范感知的工程伙伴”。接下来我将以一个全栈团队以前端React 后端Node.js为例的视角拆解如何从零构建这样一套“AI工程规范技能”并分享在实战中积累的配置技巧、避坑经验和效果评估方法。2. 核心理念与技能框架设计在开始配置具体的Skills之前我们必须先厘清一个根本问题我们希望AI在编码时扮演什么角色是一个需要详细指令的实习生还是一个能自主决策的高级工程师答案通常是介于两者之间。因此我们的技能框架设计需要兼顾“约束的刚性”和“灵活的弹性”。2.1 理解“Skills”的本质从静态规则到动态上下文很多开发者容易把Skills理解为一份放在项目根目录的配置文件比如.claude_config.json。这没错但这只是载体。Skills的本质是高度结构化的、场景化的上下文提示Prompt。它与普通Prompt的关键区别在于系统性它不是零散的技巧而是一个覆盖编码全生命周期的规则体系。可组合性不同的Skill可以像乐高一样组合针对“写API接口”、“修样式Bug”、“写单元测试”等不同任务启用不同的技能组合。可验证性AI依据Skill生成的输出其合规性可以通过自动化工具如ESLint、Prettier或人工检查点进行快速验证。基于这个理解我们可以将工程规范拆解为几个层次并对应设计SkillL1 基础格式规范 (非协商性规则)这是底线必须无条件遵守。例如缩进、引号、分号、行尾符号。这部分Skill通常直接对接项目的ESLint和Prettier配置AI生成的代码必须能通过eslint --fix和prettier --write。L2 项目结构规范 (强约束性规则)涉及文件/目录命名、模块导入导出方式、公共组件/工具函数的位置。例如“/components用于存放全局通用组件/hooks用于存放自定义React Hooks”。L3 编码最佳实践 (指导性规则)这部分更灵活是代码质量的体现。例如“React组件优先使用函数式组件和Hooks”、“避免在组件内部定义内联函数”、“API请求层必须使用统一的request封装并处理错误”。L4 领域特定逻辑 (业务约束规则)这是最有价值的Skill与你的业务强相关。例如“用户状态管理必须通过authStore禁止直接操作localStorage”、“支付相关的金额计算必须使用Big.js库以避免浮点数精度问题”。2.2 构建你的“-8 Skills”核心技能包“-8”不是一个魔法数字它代表了一套基础而全面的技能组合。你可以根据项目情况增减。以下是一个典型的“-8 Skills”包设计代码格式化与静态检查技能集成项目现有的.eslintrc.js和.prettierrc。不仅要告诉AI规则还要提供自动修复命令。例如“请确保代码符合项目ESLint规则如有格式问题请在代码块后附上可运行的修复命令。”项目结构与路径别名技能明确说明src目录下的结构以及配置的路径别名如代表src。防止AI生成类似../../../components/Button的混乱路径。API交互规范技能定义如何发送请求、处理响应和错误。例如“所有HTTP请求必须使用src/utils/request.ts中封装的request函数。成功响应需解构data字段错误必须被全局拦截器处理并弹出提示。”状态管理约定技能针对Zustand、Redux Toolkit、Valtio等说明状态切片如何组织、如何消费。例如“全局状态定义在src/stores目录下使用Zustand。组件内使用状态时应通过useStorehook选择性订阅避免整个store变化导致重渲染。”UI组件使用与创建技能规定何时使用现有组件库如Ant Design何时创建新组件以及组件的代码模板。例如“表单元素优先使用Form和Input组件。新建业务组件需放在src/components/business下使用export const ComponentName: React.FC ({...}) {}格式。”类型定义技能对TypeScript项目至关重要。规定interface和type的使用场景、泛型约束、以及类型文件存放位置是内联还是放在src/types下。测试规范技能说明单元测试Jest/Vitest和E2E测试Playwright/Cypress的编写规范、文件命名*.test.ts和放置位置同目录或__tests__。安全与性能红线技能列出绝对禁止的模式和推荐的最佳实践。例如“禁止将敏感信息如API密钥硬编码在前端代码中”、“列表渲染必须为项提供稳定的key”、“大尺寸图片必须使用懒加载或CDN优化”。注意不要试图在一个Skill里塞进所有规则。这会导致上下文过长AI可能忽略后半部分。应该按上述分类创建多个清晰、专注的Skill文件或提示片段在需要时组合使用。2.3 技能的组织与存储策略这些Skills如何管理我推荐两种方式方式一集中式配置文件。在项目根目录创建.claude/目录里面存放formatting.md、api_convention.md、structure.md等Markdown文件。每个文件描述一个技能。在给AI下指令时通过文件引用或复制关键内容到上下文。方式二动态提示模板。使用像cursor rules或自定义的IDE插件将上述技能转化为AI指令模板。当你触发“生成React组件”时插件自动将对应的组件规范Skill附加到你的问题前。我个人更倾向于方式一因为它版本可控Skill文件可以提交到Git团队共享和迭代。清晰透明每个开发者都能看到并理解AI被施加了哪些约束。便于调试当AI行为不符合预期时可以检查对应的Skill文件是否描述清晰。3. 实战配置以前端React项目为例理论说再多不如动手。我们以一个使用Vite React TypeScript Ant Design的现代前端项目为例看看如何具体配置和运用这些Skills。3.1 环境准备与基础配置首先确保你的项目已经配置了完善的代码质量工具这是AI技能生效的基石。ESLint Prettier这是强制AI遵守格式规范的“尚方宝剑”。你的.eslintrc.cjs和.prettierrc应该已经包含了团队规则。关键是要确保配置足够严格和自动修复。路径别名在vite.config.ts和tsconfig.json中配置好 - src。这是让AI生成正确导入语句的前提。创建技能目录在项目根目录下新建.claude文件夹并初始化技能文件。mkdir .claude cd .claude touch README.md # 技能目录说明 touch 01_formatting.md touch 02_project_structure.md touch 03_api_convention.md touch 04_component_guide.md3.2 编写核心技能文件接下来我们填充这些技能文件。记住描述要具体、可操作、带示例。文件.claude/01_formatting.md# 技能代码格式化与检查 ## 核心规则 1. 代码风格必须严格遵循项目中的 .eslintrc.cjs 和 .prettierrc 配置。 2. 生成代码后必须能通过以下命令检查无错误和修复 bash npm run lint # 运行ESLint检查 npm run format # 使用Prettier格式化 3. 如果生成的代码存在可自动修复的格式问题**请在代码块后附上具体的修复命令**。 ## 关键点示例 - **缩进**使用2个空格。 - **引号**JavaScript/TypeScript中使用单引号()JSX属性使用双引号()。 - **分号**行尾不加分号。 - **行宽**最大80字符。 ## 给AI的指令模板 “请遵循项目的ESLint和Prettier配置生成代码。生成后请说明如何用 npm run lint 和 npm run format 验证。”文件.claude/02_project_structure.md# 技能项目结构与路径 ## 目录结构src/ ├── api/ # 所有API请求函数 ├── assets/ # 静态资源 ├── components/ # 通用UI组件 │ ├── common/ # 全局通用组件如Loading, ErrorBoundary │ └── business/ # 业务相关组件 ├── hooks/ # 自定义React Hooks ├── layouts/ # 页面布局组件 ├── pages/ # 页面组件对应路由 ├── routers/ # 路由配置 ├── stores/ # 状态管理Zustand ├── styles/ # 全局样式、主题 ├── types/ # TypeScript类型定义 ├── utils/ # 工具函数 └── main.tsx## 路径别名 - 指向 src 目录。例如import Button from /components/common/Button; - **绝对禁止**使用相对路径进行深层引用如 ../../../../components。 ## 给AI的指令模板 “请使用路径别名 来导入模块。新建的组件请根据其用途放入 /components/common/ 或 /components/business/。”文件.claude/03_api_convention.md# 技能API交互规范 ## 请求层 所有HTTP请求必须使用 /utils/request.ts 中封装的 request 函数。该函数已处理 - 基础URL配置 - 请求/响应拦截器 - 错误统一处理会调用 message.error 显示后端错误信息 ## 函数定义规范 1. API函数统一放在 /api/ 目录下按模块分文件如 user.ts, product.ts。 2. 使用TypeScript明确定义请求参数类型和响应类型。 3. 函数命名采用 动词名词 形式如 getUserInfo, createOrder。 ## 示例模板 typescript // /api/user.ts import { request } from /utils/request; export interface LoginParams { username: string; password: string; } export interface UserInfo { id: number; name: string; avatar: string; } export const login (data: LoginParams) { return request.postUserInfo(/api/auth/login, data); }; export const getUserProfile (userId: number) { return request.getUserInfo(/api/user/${userId}); };给AI的指令模板“请将API请求函数定义在/api/目录下对应的模块文件中。必须使用/utils/request.ts中的request方法并明确定义请求和响应类型。”**文件.claude/04_component_guide.md** markdown # 技能React组件编写指南 ## 组件类型 1. **通用组件** (/components/common/): 高度可复用无业务逻辑通过Props配置。 2. **业务组件** (/components/business/): 包含特定业务逻辑通常在单个页面或模块内复用。 ## 函数式组件模板 typescript import React, { useState, useEffect } from react; import { SomeAntdComponent } from antd; import { someHook } from /hooks/useSomething; import styles from ./index.module.less; // 推荐使用CSS Modules interface ComponentNameProps { title: string; value?: number; onChange?: (newValue: number) void; } export const ComponentName: React.FCComponentNameProps ({ title, value 0, onChange, }) { const [internalState, setInternalState] useStatestring(); // 使用自定义Hook管理复杂逻辑 const { data, isLoading } someHook(); const handleClick () { // 避免内联函数定义除非非常简单 console.log(clicked); onChange?.(value 1); }; return ( div className{styles.wrapper} h3{title}/h3 SomeAntdComponent value{value} onChange{onChange} / {/* 列表渲染必须提供key */} {data.map((item) ( div key{item.id}{item.name}/div ))} /div ); };关键规则优先使用函数式组件和Hooks。Props必须使用TypeScript接口明确定义。避免在渲染函数内创建新的函数或对象除非使用useMemo/useCallback优化。复杂逻辑应抽离到自定义Hook中放在/hooks/。给AI的指令模板“请按照上述函数式组件模板创建React组件。Props需定义接口组件内复杂逻辑考虑抽离为自定义Hook。使用CSS Modules进行样式隔离。”### 3.3 在Claude/Cursor中激活技能 有了技能文件下一步就是让AI在编码时“看到”它们。这里有几个实用技巧 * **直接复制粘贴**对于简单的任务直接将相关技能文件的内容复制到对话的开头。例如“请帮我创建一个用户登录表单组件。以下是我们的组件规范[粘贴04_component_guide.md的核心内容]”。 * **使用“规则”功能**像Cursor编辑器内置了“规则”功能。你可以在项目设置中将.claude目录下的技能文件内容添加为全局或项目级规则。这样AI在回答任何编码问题时都会自动参考这些规则。 * **创建快捷指令**在IDE中设置代码片段或快捷键将常用的技能组合如“创建API函数”快速插入到提问中。 **一个实战交互示例** * **你的指令**“在/pages/user/Profile.tsx页面中我需要一个展示用户基本信息并允许编辑昵称的模块。请遵循我们的组件和API规范。” * **AI的思考过程理想情况** 1. 读取04_component_guide.md知道要创建业务组件放在/components/business/下使用函数式组件模板。 2. 读取03_api_convention.md知道要去/api/user.ts中查找或创建getUserProfile和updateUserNickname函数。 3. 读取02_project_structure.md知道如何正确导入/components/business/下的组件和/api/user。 4. 生成代码后会附带一句“生成的代码符合项目ESLint配置你可以运行npm run lint进行检查。” 通过这种方式AI生成的代码在结构、格式、甚至命名上都会高度符合团队习惯大大减少了后续调整的工作量。 ## 4. 高级技巧动态技能组合与上下文管理 基础技能能解决80%的问题但面对复杂场景我们需要更智能的技能调度策略。核心挑战是**如何在不超出AI上下文窗口限制的前提下提供最相关、最有效的规则**。 ### 4.1 基于任务的技能路由 不要总是把全部8个技能都塞给AI。根据当前任务动态选择 * **任务修复一个样式Bug** * **激活技能**01_formatting.md (确保修改符合格式) 04_component_guide.md (了解组件结构) * **可省略技能**03_api_convention.md, 02_project_structure.md (如果未涉及API和新建文件) * **任务开发一个新的设置页面** * **激活技能**02_project_structure.md (创建正确位置的文件) 04_component_guide.md (编写组件) 03_api_convention.md (可能需要调用获取/更新设置接口) * **可省略技能**01_formatting.md (可作为基础要求始终隐含) 你可以通过创建“元技能”文件来实现这种路由。例如创建一个.claude/task_router.md markdown # 任务技能路由指南 根据用户请求的关键词决定附加哪些技能文件 - 如果请求包含“组件”、“Button”、“Modal” - 附加 component_guide.md - 如果请求包含“API”、“请求”、“接口”、“fetch” - 附加 api_convention.md - 如果请求包含“页面”、“新建文件”、“目录” - 附加 project_structure.md - 所有代码生成请求默认隐含 formatting.md 的要求。虽然当前AI还不能完全自动化地读取这个路由文件但你可以手动参照它来组合技能或者在构建更复杂的AI Agent时将此逻辑编程实现。4.2 处理技能冲突与优先级有时技能之间可能存在冲突。例如格式化技能要求行宽80字符但某个复杂JSX表达式不可避免地会超长。这时需要设定优先级。实操心得我建议的优先级是业务逻辑正确性 功能性约束API/状态 项目结构 代码格式。格式问题最容易用工具自动修复而错误的业务逻辑或架构决策代价更高。在给AI的指令中可以明确说明“首要保证功能正确其次遵守API和状态管理规范格式问题可以稍后通过Prettier修复。”4.3 技能的迭代与优化Skills不是一成不变的。你需要一个反馈循环来优化它们。收集“违规”案例定期检查AI生成的、需要人工大幅修改的代码。分析原因是Skill描述不清还是存在未覆盖的边界情况更新技能文件将常见的“违规”模式转化为更明确的规则添加到对应的技能文件中。例如如果发现AI总在组件里直接写fetch就在api_convention.md里用更醒目的方式强调禁止条款。进行“技能测试”像写单元测试一样测试你的Skills。给出一个模糊的指令如“帮我写个登录函数”看AI是否能生成完全符合所有规范的代码。如果不能就调整技能描述。5. 效果评估与常见问题排查投入时间搭建Skills后如何衡量其效果又该如何解决AI“不听话”的问题5.1 效果评估指标可以从以下几个维度评估代码合并前修改量对比使用Skills前后AI生成的代码在Code Review中需要修改的行数/处数是否显著下降。理想情况是仅需修改业务逻辑细节而无需调整风格和结构。规范符合度随机抽样AI生成的代码用ESLint和自定义的规范检查脚本如有跑一遍统计通过率。开发效率衡量完成特定类型任务如增删改查页面的平均时间是否缩短重点是节省了多少用于调整代码结构、格式的“非创造性”时间。团队满意度通过简单的问卷了解团队成员是否觉得AI生成的代码更“顺眼”、更容易接手和维护。5.2 常见问题与解决方案即使有了详细的SkillsAI有时还是会“跑偏”。以下是几个常见问题及排查思路问题1AI完全忽略了某个重要技能比如还是用了相对路径。可能原因上下文太长技能描述被挤到了后面AI的注意力分散了。解决方案精简技能描述只保留最核心、必须遵守的条款去掉解释性文字。用更简短的命令式语句。前置强调在对话的最开始用加粗或单独段落重申最重要的1-2条规则。例如“最重要必须使用路径别名禁止使用相对路径”分步引导不要一次性要求AI做太多事。先让它“按照规范创建/api/user.ts文件”再让它“在组件中调用这个API”。问题2AI生成的代码符合技能描述但不符合“潜规则”或最新实践。可能原因技能文件更新不及时或者有些团队默契没有文档化。解决方案这正是Skills机制的价值所在——倒逼团队将隐性知识显性化。一旦发现这种“潜规则”立即将其写入对应的技能文件。例如团队最近决定所有新组件默认使用CSS-in-JS而不是CSS Modules就要及时更新04_component_guide.md。问题3针对非常具体、复杂的业务逻辑技能描述起来很困难。可能原因业务逻辑本身过于复杂难以用几条规则概括。解决方案提供高质量示例与其用文字描述复杂的计算逻辑不如在技能文件中直接提供一个正确的、典型的代码示例。AI非常擅长从示例中学习和模仿模式。使用“种子代码”先由资深开发者写出核心逻辑的框架或关键函数种子代码然后让AI基于此框架和Skills去补全剩余部分如样式、错误处理等。问题4不同AI模型Claude-3, GPT-4, DeepSeek Coder对同一技能的理解和执行力有差异。可能原因不同模型的训练数据、指令遵循能力和上下文处理方式不同。解决方案为不同模型微调提示词你可能需要为Claude和GPT准备略微不同的技能描述版本以适应其“性格”。例如Claude可能对结构化列表响应更好而GPT-4可能更需要清晰的因果描述。标准化输入尽量使用清晰、无歧义、结构化的描述如Markdown列表、明确的“Do”和“Don‘t”这能提高不同模型间的一致性。6. 技能体系的扩展与未来展望基础的“-8 Skills”覆盖了单项目前端开发的核心规范。但随着技术栈复杂化和团队协作深化这套体系可以进一步扩展。6.1 向后端与全栈场景扩展对于Node.js后端如NestJS或Express可以创建对应的技能包目录结构技能规范src/controllers,src/services,src/entities,src/dtos等目录的职责。API设计技能定义RESTful端点命名规范、状态码使用、响应体封装格式如{ code: 0, data: {}, message: success }。数据库操作技能规定必须使用ORM如TypeORM/Prisma如何编写Repository事务处理的最佳实践。错误处理技能统一全局异常过滤器、业务错误码定义、日志记录格式。安全规范技能输入验证使用class-validator、SQL注入防护、身份认证/授权中间件使用规范。对于全栈任务你可以组合前端和后端技能让AI理解从接口定义到前端调用的完整数据流。6.2 集成到CI/CD与团队工作流Skills的价值不仅在于辅助编码更在于保证代码库的长期一致性。自动化校验可以编写一个简单的脚本在CI流水线中对新生成的或AI修改过的代码进行“规范符合度”检查比如检查是否使用了正确的API封装函数或者组件是否放在了正确目录。新人 onboarding将.claude技能目录作为项目文档的一部分。新成员通过学习这些技能文件能快速理解团队的工程实践和代码风格这比阅读零散的文档更高效。代码库一致性当多个AI助手或多个开发者同时在一个项目上工作时Skills成为统一的“宪法”确保无论谁或哪个AI写的代码都遵循同一套标准极大降低了维护成本。6.3 面向AI编程范式的思考最终我们构建的不仅仅是一套技能文件而是一种面向AI的、声明式的工程规范表达方式。传统的规范是写给人看的依赖人的理解和记忆。而Skills是写给AI以及通过AI间接影响人看的它需要更精确、更结构化、更可执行。这促使我们重新思考哪些规范是真正核心、必须固化的哪些可以交给AI在约束下自由发挥如何设计规范才能在保证质量的同时不扼杀创造力和效率实践“Claude Code -8 Skills”的过程本身就是对团队工程文化和技术管理的一次深度梳理和优化。它的最大回报可能不是今天少敲了几行代码而是明天整个代码库依然清晰、一致、易于维护无论它是由人、AI还是两者协作共同书写。 AI编程规范实战：让Claude/Cursor生成符合团队规范的代码
1. 项目概述当AI助手开始理解你的代码规范最近在团队里推广AI编程助手发现一个挺普遍的现象新同事用Claude或者Cursor写代码生成速度是快但代码风格五花八门有的用双引号有的用单引号缩进是两个空格还是四个空格全看AI当天心情更别提项目特有的目录结构、组件命名这些深层规范了。每次Code Review都得花大量时间纠正格式问题而不是聚焦在逻辑和架构上。这让我意识到仅仅让AI“写出能跑的代码”是远远不够的我们真正需要的是让它成为理解并遵守团队工程规范的“智能协作者”。这就是“Claude Code -8 Skills 实战指南”要解决的核心问题。这里的“Claude Code”并非指某个特定软件而是一种方法论和实践集合核心是利用Claude等大模型特别是其Code版本或相关技能的“Skills”技能机制将你团队的工程规范——包括代码风格、架构模式、安全规则、甚至评审要点——转化为AI可理解、可执行的指令集。而“-8 Skills”更像是一个代号代表一套经过精心设计和组合的、用于约束和引导AI编码行为的核心技能包。简单说就是教AI按你的规矩办事让它生成的代码从第一行起就是“可合并”的状态。这不仅仅是配置一个linter那么简单。它涉及如何将模糊的、基于经验的“好代码标准”结构化如何将这些标准有效地“注入”到AI的上下文窗口以及如何在不同的开发场景如新建文件、重构旧代码、修复Bug下动态调整AI的行为。对于前端、后端、移动端等不同技术栈的团队这套方法的实践细节各不相同但其思维模型是相通的将AI从“代码生成器”升级为“规范感知的工程伙伴”。接下来我将以一个全栈团队以前端React 后端Node.js为例的视角拆解如何从零构建这样一套“AI工程规范技能”并分享在实战中积累的配置技巧、避坑经验和效果评估方法。2. 核心理念与技能框架设计在开始配置具体的Skills之前我们必须先厘清一个根本问题我们希望AI在编码时扮演什么角色是一个需要详细指令的实习生还是一个能自主决策的高级工程师答案通常是介于两者之间。因此我们的技能框架设计需要兼顾“约束的刚性”和“灵活的弹性”。2.1 理解“Skills”的本质从静态规则到动态上下文很多开发者容易把Skills理解为一份放在项目根目录的配置文件比如.claude_config.json。这没错但这只是载体。Skills的本质是高度结构化的、场景化的上下文提示Prompt。它与普通Prompt的关键区别在于系统性它不是零散的技巧而是一个覆盖编码全生命周期的规则体系。可组合性不同的Skill可以像乐高一样组合针对“写API接口”、“修样式Bug”、“写单元测试”等不同任务启用不同的技能组合。可验证性AI依据Skill生成的输出其合规性可以通过自动化工具如ESLint、Prettier或人工检查点进行快速验证。基于这个理解我们可以将工程规范拆解为几个层次并对应设计SkillL1 基础格式规范 (非协商性规则)这是底线必须无条件遵守。例如缩进、引号、分号、行尾符号。这部分Skill通常直接对接项目的ESLint和Prettier配置AI生成的代码必须能通过eslint --fix和prettier --write。L2 项目结构规范 (强约束性规则)涉及文件/目录命名、模块导入导出方式、公共组件/工具函数的位置。例如“/components用于存放全局通用组件/hooks用于存放自定义React Hooks”。L3 编码最佳实践 (指导性规则)这部分更灵活是代码质量的体现。例如“React组件优先使用函数式组件和Hooks”、“避免在组件内部定义内联函数”、“API请求层必须使用统一的request封装并处理错误”。L4 领域特定逻辑 (业务约束规则)这是最有价值的Skill与你的业务强相关。例如“用户状态管理必须通过authStore禁止直接操作localStorage”、“支付相关的金额计算必须使用Big.js库以避免浮点数精度问题”。2.2 构建你的“-8 Skills”核心技能包“-8”不是一个魔法数字它代表了一套基础而全面的技能组合。你可以根据项目情况增减。以下是一个典型的“-8 Skills”包设计代码格式化与静态检查技能集成项目现有的.eslintrc.js和.prettierrc。不仅要告诉AI规则还要提供自动修复命令。例如“请确保代码符合项目ESLint规则如有格式问题请在代码块后附上可运行的修复命令。”项目结构与路径别名技能明确说明src目录下的结构以及配置的路径别名如代表src。防止AI生成类似../../../components/Button的混乱路径。API交互规范技能定义如何发送请求、处理响应和错误。例如“所有HTTP请求必须使用src/utils/request.ts中封装的request函数。成功响应需解构data字段错误必须被全局拦截器处理并弹出提示。”状态管理约定技能针对Zustand、Redux Toolkit、Valtio等说明状态切片如何组织、如何消费。例如“全局状态定义在src/stores目录下使用Zustand。组件内使用状态时应通过useStorehook选择性订阅避免整个store变化导致重渲染。”UI组件使用与创建技能规定何时使用现有组件库如Ant Design何时创建新组件以及组件的代码模板。例如“表单元素优先使用Form和Input组件。新建业务组件需放在src/components/business下使用export const ComponentName: React.FC ({...}) {}格式。”类型定义技能对TypeScript项目至关重要。规定interface和type的使用场景、泛型约束、以及类型文件存放位置是内联还是放在src/types下。测试规范技能说明单元测试Jest/Vitest和E2E测试Playwright/Cypress的编写规范、文件命名*.test.ts和放置位置同目录或__tests__。安全与性能红线技能列出绝对禁止的模式和推荐的最佳实践。例如“禁止将敏感信息如API密钥硬编码在前端代码中”、“列表渲染必须为项提供稳定的key”、“大尺寸图片必须使用懒加载或CDN优化”。注意不要试图在一个Skill里塞进所有规则。这会导致上下文过长AI可能忽略后半部分。应该按上述分类创建多个清晰、专注的Skill文件或提示片段在需要时组合使用。2.3 技能的组织与存储策略这些Skills如何管理我推荐两种方式方式一集中式配置文件。在项目根目录创建.claude/目录里面存放formatting.md、api_convention.md、structure.md等Markdown文件。每个文件描述一个技能。在给AI下指令时通过文件引用或复制关键内容到上下文。方式二动态提示模板。使用像cursor rules或自定义的IDE插件将上述技能转化为AI指令模板。当你触发“生成React组件”时插件自动将对应的组件规范Skill附加到你的问题前。我个人更倾向于方式一因为它版本可控Skill文件可以提交到Git团队共享和迭代。清晰透明每个开发者都能看到并理解AI被施加了哪些约束。便于调试当AI行为不符合预期时可以检查对应的Skill文件是否描述清晰。3. 实战配置以前端React项目为例理论说再多不如动手。我们以一个使用Vite React TypeScript Ant Design的现代前端项目为例看看如何具体配置和运用这些Skills。3.1 环境准备与基础配置首先确保你的项目已经配置了完善的代码质量工具这是AI技能生效的基石。ESLint Prettier这是强制AI遵守格式规范的“尚方宝剑”。你的.eslintrc.cjs和.prettierrc应该已经包含了团队规则。关键是要确保配置足够严格和自动修复。路径别名在vite.config.ts和tsconfig.json中配置好 - src。这是让AI生成正确导入语句的前提。创建技能目录在项目根目录下新建.claude文件夹并初始化技能文件。mkdir .claude cd .claude touch README.md # 技能目录说明 touch 01_formatting.md touch 02_project_structure.md touch 03_api_convention.md touch 04_component_guide.md3.2 编写核心技能文件接下来我们填充这些技能文件。记住描述要具体、可操作、带示例。文件.claude/01_formatting.md# 技能代码格式化与检查 ## 核心规则 1. 代码风格必须严格遵循项目中的 .eslintrc.cjs 和 .prettierrc 配置。 2. 生成代码后必须能通过以下命令检查无错误和修复 bash npm run lint # 运行ESLint检查 npm run format # 使用Prettier格式化 3. 如果生成的代码存在可自动修复的格式问题**请在代码块后附上具体的修复命令**。 ## 关键点示例 - **缩进**使用2个空格。 - **引号**JavaScript/TypeScript中使用单引号()JSX属性使用双引号()。 - **分号**行尾不加分号。 - **行宽**最大80字符。 ## 给AI的指令模板 “请遵循项目的ESLint和Prettier配置生成代码。生成后请说明如何用 npm run lint 和 npm run format 验证。”文件.claude/02_project_structure.md# 技能项目结构与路径 ## 目录结构src/ ├── api/ # 所有API请求函数 ├── assets/ # 静态资源 ├── components/ # 通用UI组件 │ ├── common/ # 全局通用组件如Loading, ErrorBoundary │ └── business/ # 业务相关组件 ├── hooks/ # 自定义React Hooks ├── layouts/ # 页面布局组件 ├── pages/ # 页面组件对应路由 ├── routers/ # 路由配置 ├── stores/ # 状态管理Zustand ├── styles/ # 全局样式、主题 ├── types/ # TypeScript类型定义 ├── utils/ # 工具函数 └── main.tsx## 路径别名 - 指向 src 目录。例如import Button from /components/common/Button; - **绝对禁止**使用相对路径进行深层引用如 ../../../../components。 ## 给AI的指令模板 “请使用路径别名 来导入模块。新建的组件请根据其用途放入 /components/common/ 或 /components/business/。”文件.claude/03_api_convention.md# 技能API交互规范 ## 请求层 所有HTTP请求必须使用 /utils/request.ts 中封装的 request 函数。该函数已处理 - 基础URL配置 - 请求/响应拦截器 - 错误统一处理会调用 message.error 显示后端错误信息 ## 函数定义规范 1. API函数统一放在 /api/ 目录下按模块分文件如 user.ts, product.ts。 2. 使用TypeScript明确定义请求参数类型和响应类型。 3. 函数命名采用 动词名词 形式如 getUserInfo, createOrder。 ## 示例模板 typescript // /api/user.ts import { request } from /utils/request; export interface LoginParams { username: string; password: string; } export interface UserInfo { id: number; name: string; avatar: string; } export const login (data: LoginParams) { return request.postUserInfo(/api/auth/login, data); }; export const getUserProfile (userId: number) { return request.getUserInfo(/api/user/${userId}); };给AI的指令模板“请将API请求函数定义在/api/目录下对应的模块文件中。必须使用/utils/request.ts中的request方法并明确定义请求和响应类型。”**文件.claude/04_component_guide.md** markdown # 技能React组件编写指南 ## 组件类型 1. **通用组件** (/components/common/): 高度可复用无业务逻辑通过Props配置。 2. **业务组件** (/components/business/): 包含特定业务逻辑通常在单个页面或模块内复用。 ## 函数式组件模板 typescript import React, { useState, useEffect } from react; import { SomeAntdComponent } from antd; import { someHook } from /hooks/useSomething; import styles from ./index.module.less; // 推荐使用CSS Modules interface ComponentNameProps { title: string; value?: number; onChange?: (newValue: number) void; } export const ComponentName: React.FCComponentNameProps ({ title, value 0, onChange, }) { const [internalState, setInternalState] useStatestring(); // 使用自定义Hook管理复杂逻辑 const { data, isLoading } someHook(); const handleClick () { // 避免内联函数定义除非非常简单 console.log(clicked); onChange?.(value 1); }; return ( div className{styles.wrapper} h3{title}/h3 SomeAntdComponent value{value} onChange{onChange} / {/* 列表渲染必须提供key */} {data.map((item) ( div key{item.id}{item.name}/div ))} /div ); };关键规则优先使用函数式组件和Hooks。Props必须使用TypeScript接口明确定义。避免在渲染函数内创建新的函数或对象除非使用useMemo/useCallback优化。复杂逻辑应抽离到自定义Hook中放在/hooks/。给AI的指令模板“请按照上述函数式组件模板创建React组件。Props需定义接口组件内复杂逻辑考虑抽离为自定义Hook。使用CSS Modules进行样式隔离。”### 3.3 在Claude/Cursor中激活技能 有了技能文件下一步就是让AI在编码时“看到”它们。这里有几个实用技巧 * **直接复制粘贴**对于简单的任务直接将相关技能文件的内容复制到对话的开头。例如“请帮我创建一个用户登录表单组件。以下是我们的组件规范[粘贴04_component_guide.md的核心内容]”。 * **使用“规则”功能**像Cursor编辑器内置了“规则”功能。你可以在项目设置中将.claude目录下的技能文件内容添加为全局或项目级规则。这样AI在回答任何编码问题时都会自动参考这些规则。 * **创建快捷指令**在IDE中设置代码片段或快捷键将常用的技能组合如“创建API函数”快速插入到提问中。 **一个实战交互示例** * **你的指令**“在/pages/user/Profile.tsx页面中我需要一个展示用户基本信息并允许编辑昵称的模块。请遵循我们的组件和API规范。” * **AI的思考过程理想情况** 1. 读取04_component_guide.md知道要创建业务组件放在/components/business/下使用函数式组件模板。 2. 读取03_api_convention.md知道要去/api/user.ts中查找或创建getUserProfile和updateUserNickname函数。 3. 读取02_project_structure.md知道如何正确导入/components/business/下的组件和/api/user。 4. 生成代码后会附带一句“生成的代码符合项目ESLint配置你可以运行npm run lint进行检查。” 通过这种方式AI生成的代码在结构、格式、甚至命名上都会高度符合团队习惯大大减少了后续调整的工作量。 ## 4. 高级技巧动态技能组合与上下文管理 基础技能能解决80%的问题但面对复杂场景我们需要更智能的技能调度策略。核心挑战是**如何在不超出AI上下文窗口限制的前提下提供最相关、最有效的规则**。 ### 4.1 基于任务的技能路由 不要总是把全部8个技能都塞给AI。根据当前任务动态选择 * **任务修复一个样式Bug** * **激活技能**01_formatting.md (确保修改符合格式) 04_component_guide.md (了解组件结构) * **可省略技能**03_api_convention.md, 02_project_structure.md (如果未涉及API和新建文件) * **任务开发一个新的设置页面** * **激活技能**02_project_structure.md (创建正确位置的文件) 04_component_guide.md (编写组件) 03_api_convention.md (可能需要调用获取/更新设置接口) * **可省略技能**01_formatting.md (可作为基础要求始终隐含) 你可以通过创建“元技能”文件来实现这种路由。例如创建一个.claude/task_router.md markdown # 任务技能路由指南 根据用户请求的关键词决定附加哪些技能文件 - 如果请求包含“组件”、“Button”、“Modal” - 附加 component_guide.md - 如果请求包含“API”、“请求”、“接口”、“fetch” - 附加 api_convention.md - 如果请求包含“页面”、“新建文件”、“目录” - 附加 project_structure.md - 所有代码生成请求默认隐含 formatting.md 的要求。虽然当前AI还不能完全自动化地读取这个路由文件但你可以手动参照它来组合技能或者在构建更复杂的AI Agent时将此逻辑编程实现。4.2 处理技能冲突与优先级有时技能之间可能存在冲突。例如格式化技能要求行宽80字符但某个复杂JSX表达式不可避免地会超长。这时需要设定优先级。实操心得我建议的优先级是业务逻辑正确性 功能性约束API/状态 项目结构 代码格式。格式问题最容易用工具自动修复而错误的业务逻辑或架构决策代价更高。在给AI的指令中可以明确说明“首要保证功能正确其次遵守API和状态管理规范格式问题可以稍后通过Prettier修复。”4.3 技能的迭代与优化Skills不是一成不变的。你需要一个反馈循环来优化它们。收集“违规”案例定期检查AI生成的、需要人工大幅修改的代码。分析原因是Skill描述不清还是存在未覆盖的边界情况更新技能文件将常见的“违规”模式转化为更明确的规则添加到对应的技能文件中。例如如果发现AI总在组件里直接写fetch就在api_convention.md里用更醒目的方式强调禁止条款。进行“技能测试”像写单元测试一样测试你的Skills。给出一个模糊的指令如“帮我写个登录函数”看AI是否能生成完全符合所有规范的代码。如果不能就调整技能描述。5. 效果评估与常见问题排查投入时间搭建Skills后如何衡量其效果又该如何解决AI“不听话”的问题5.1 效果评估指标可以从以下几个维度评估代码合并前修改量对比使用Skills前后AI生成的代码在Code Review中需要修改的行数/处数是否显著下降。理想情况是仅需修改业务逻辑细节而无需调整风格和结构。规范符合度随机抽样AI生成的代码用ESLint和自定义的规范检查脚本如有跑一遍统计通过率。开发效率衡量完成特定类型任务如增删改查页面的平均时间是否缩短重点是节省了多少用于调整代码结构、格式的“非创造性”时间。团队满意度通过简单的问卷了解团队成员是否觉得AI生成的代码更“顺眼”、更容易接手和维护。5.2 常见问题与解决方案即使有了详细的SkillsAI有时还是会“跑偏”。以下是几个常见问题及排查思路问题1AI完全忽略了某个重要技能比如还是用了相对路径。可能原因上下文太长技能描述被挤到了后面AI的注意力分散了。解决方案精简技能描述只保留最核心、必须遵守的条款去掉解释性文字。用更简短的命令式语句。前置强调在对话的最开始用加粗或单独段落重申最重要的1-2条规则。例如“最重要必须使用路径别名禁止使用相对路径”分步引导不要一次性要求AI做太多事。先让它“按照规范创建/api/user.ts文件”再让它“在组件中调用这个API”。问题2AI生成的代码符合技能描述但不符合“潜规则”或最新实践。可能原因技能文件更新不及时或者有些团队默契没有文档化。解决方案这正是Skills机制的价值所在——倒逼团队将隐性知识显性化。一旦发现这种“潜规则”立即将其写入对应的技能文件。例如团队最近决定所有新组件默认使用CSS-in-JS而不是CSS Modules就要及时更新04_component_guide.md。问题3针对非常具体、复杂的业务逻辑技能描述起来很困难。可能原因业务逻辑本身过于复杂难以用几条规则概括。解决方案提供高质量示例与其用文字描述复杂的计算逻辑不如在技能文件中直接提供一个正确的、典型的代码示例。AI非常擅长从示例中学习和模仿模式。使用“种子代码”先由资深开发者写出核心逻辑的框架或关键函数种子代码然后让AI基于此框架和Skills去补全剩余部分如样式、错误处理等。问题4不同AI模型Claude-3, GPT-4, DeepSeek Coder对同一技能的理解和执行力有差异。可能原因不同模型的训练数据、指令遵循能力和上下文处理方式不同。解决方案为不同模型微调提示词你可能需要为Claude和GPT准备略微不同的技能描述版本以适应其“性格”。例如Claude可能对结构化列表响应更好而GPT-4可能更需要清晰的因果描述。标准化输入尽量使用清晰、无歧义、结构化的描述如Markdown列表、明确的“Do”和“Don‘t”这能提高不同模型间的一致性。6. 技能体系的扩展与未来展望基础的“-8 Skills”覆盖了单项目前端开发的核心规范。但随着技术栈复杂化和团队协作深化这套体系可以进一步扩展。6.1 向后端与全栈场景扩展对于Node.js后端如NestJS或Express可以创建对应的技能包目录结构技能规范src/controllers,src/services,src/entities,src/dtos等目录的职责。API设计技能定义RESTful端点命名规范、状态码使用、响应体封装格式如{ code: 0, data: {}, message: success }。数据库操作技能规定必须使用ORM如TypeORM/Prisma如何编写Repository事务处理的最佳实践。错误处理技能统一全局异常过滤器、业务错误码定义、日志记录格式。安全规范技能输入验证使用class-validator、SQL注入防护、身份认证/授权中间件使用规范。对于全栈任务你可以组合前端和后端技能让AI理解从接口定义到前端调用的完整数据流。6.2 集成到CI/CD与团队工作流Skills的价值不仅在于辅助编码更在于保证代码库的长期一致性。自动化校验可以编写一个简单的脚本在CI流水线中对新生成的或AI修改过的代码进行“规范符合度”检查比如检查是否使用了正确的API封装函数或者组件是否放在了正确目录。新人 onboarding将.claude技能目录作为项目文档的一部分。新成员通过学习这些技能文件能快速理解团队的工程实践和代码风格这比阅读零散的文档更高效。代码库一致性当多个AI助手或多个开发者同时在一个项目上工作时Skills成为统一的“宪法”确保无论谁或哪个AI写的代码都遵循同一套标准极大降低了维护成本。6.3 面向AI编程范式的思考最终我们构建的不仅仅是一套技能文件而是一种面向AI的、声明式的工程规范表达方式。传统的规范是写给人看的依赖人的理解和记忆。而Skills是写给AI以及通过AI间接影响人看的它需要更精确、更结构化、更可执行。这促使我们重新思考哪些规范是真正核心、必须固化的哪些可以交给AI在约束下自由发挥如何设计规范才能在保证质量的同时不扼杀创造力和效率实践“Claude Code -8 Skills”的过程本身就是对团队工程文化和技术管理的一次深度梳理和优化。它的最大回报可能不是今天少敲了几行代码而是明天整个代码库依然清晰、一致、易于维护无论它是由人、AI还是两者协作共同书写。