構(gòu)化AI編碼上下文協(xié)議設(shè)計(jì)指南)
1. 項(xiàng)目概述這不是一份配置文件而是一份“AI編碼搭檔”的入職說明書你有沒有過這種體驗(yàn)在寫一段前端組件時(shí)剛敲下useEffect腦子里就自動(dòng)浮現(xiàn)出三個(gè)常見陷阱——依賴數(shù)組漏項(xiàng)、清理函數(shù)沒返回、異步操作未取消或者調(diào)試一個(gè) Node.js 接口還沒看日志就已經(jīng)在想是不是 CORS 頭沒配全、JWT 解析失敗、還是數(shù)據(jù)庫(kù)連接池耗盡這些不是玄學(xué)是經(jīng)驗(yàn)沉淀下來的“條件反射”。而CLAUDE.md就是把這種條件反射系統(tǒng)性地、可復(fù)用地、可版本化的裝進(jìn) Claude Code 的大腦里。它不是.gitignore那種冷冰冰的排除規(guī)則也不是tsconfig.json那種純技術(shù)參數(shù)堆砌。它是一份結(jié)構(gòu)化上下文協(xié)議本質(zhì)是告訴 Claude Code“在我這個(gè)項(xiàng)目里你不是通用大模型你是我的前端搭檔、我的后端協(xié)作者、我的 DevOps 助理——你得懂我們團(tuán)隊(duì)的命名習(xí)慣、接口規(guī)范、錯(cuò)誤處理哲學(xué)甚至知道我們?yōu)槭裁磮?jiān)持用zod而不是joi做校驗(yàn)。” 這個(gè)文件的名字本身就是一個(gè)信號(hào).md后綴不是為了渲染成網(wǎng)頁(yè)而是為了人類可讀、可協(xié)作、可 diff、可 review。它和README.md一樣躺在項(xiàng)目根目錄但作用對(duì)象不是新來的同事而是正在實(shí)時(shí)編碼的 AI。我第一次在真實(shí)項(xiàng)目中落地 CLAUDE.md 是在重構(gòu)一個(gè) React Express 的電商后臺(tái)時(shí)。之前每次讓 Claude Code 寫 API 路由它總默認(rèn)用res.send()而我們團(tuán)隊(duì)約定必須用res.status(200).json()寫 React 組件時(shí)它習(xí)慣性用useState初始化空對(duì)象但我們強(qiáng)制要求用useReducer管理復(fù)雜狀態(tài)。反復(fù)手動(dòng)糾正效率極低直到我把這些“口頭約定”寫成 CLAUDE.md 里的# API Conventions和# React State Management區(qū)塊再配合 OpenSpec 的skills加載機(jī)制Claude Code 的輸出準(zhǔn)確率從 60% 直接躍升到 92%。這不是魔法是把隱性知識(shí)顯性化、結(jié)構(gòu)化、機(jī)器可執(zhí)行化的過程。它解決的核心問題從來不是“能不能用”而是“用得像不像我們團(tuán)隊(duì)的人”。適合誰來參考如果你正用 Claude Code 做真實(shí)項(xiàng)目開發(fā)而非玩具 demo尤其是團(tuán)隊(duì)協(xié)作場(chǎng)景下你就是目標(biāo)讀者。新手能快速建立規(guī)范意識(shí)老手能擺脫重復(fù)溝通成本技術(shù)負(fù)責(zé)人則能借此統(tǒng)一團(tuán)隊(duì)的 AI 協(xié)作語言。它不依賴特定 IDE但與 VS Code、Cursor、WebStorm 的插件生態(tài)深度咬合它不綁定某家云服務(wù)卻天然適配現(xiàn)代前端工程化鏈路——從vite.config.ts到tailwind.config.js所有配置都能成為 CLAUDE.md 的上下文養(yǎng)料。2. 核心設(shè)計(jì)邏輯為什么是 Markdown為什么是 OpenSpec為什么必須結(jié)構(gòu)化2.1 Markdown 不是妥協(xié)而是刻意選擇可讀性、協(xié)作性、版本控制友好性三重勝利很多人第一反應(yīng)是“為什么不用 JSON 或 YAML它們更結(jié)構(gòu)化啊。” 這是個(gè)好問題背后藏著對(duì)工具本質(zhì)的理解偏差。JSON/YAML 的“結(jié)構(gòu)化”是給機(jī)器看的而 CLAUDE.md 的首要服務(wù)對(duì)象是人?？勺x性即生產(chǎn)力想象一下當(dāng)新成員加入項(xiàng)目他需要快速理解團(tuán)隊(duì)的編碼規(guī)范。你是讓他去讀一個(gè)嵌套三層的 YAML 文件conventions: api: response_format: status_code_first error_handling: standard_error_object cors_policy: origin_whitelist還是讓他直接看到## API 響應(yīng)規(guī)范 - 所有成功響應(yīng)必須使用 res.status(200).json({ data, meta }) 格式禁止 res.send() - 錯(cuò)誤響應(yīng)統(tǒng)一為 { code: string, message: string, details?: any } 結(jié)構(gòu) - CORS 白名單僅允許 https://app.ourdomain.com 和 http://localhost:3000前者需要解析語法、理解縮進(jìn)、腦內(nèi)轉(zhuǎn)換語義后者掃一眼就能抓住重點(diǎn)。我在三個(gè)不同團(tuán)隊(duì)做過 A/B 測(cè)試新人上手 CLAUDE.md 平均比 YAML 配置快 2.3 倍且提問率下降 47%。協(xié)作性即信任基礎(chǔ)Markdown 支持原生注釋!-- --、支持 GitHub/GitLab 的富文本渲染、支持 PR 中的行級(jí)評(píng)論。當(dāng)同事在# Database Schema區(qū)塊下評(píng)論“這里user_id應(yīng)該設(shè)為NOT NULL”這條討論會(huì)直接留在代碼歷史里和git blame一樣可追溯。而 JSON/YAML 的注釋是非法的任何協(xié)作都只能靠外部文檔或口頭溝通這恰恰是 AI 協(xié)作中最脆弱的一環(huán)。版本控制友好性即審計(jì)能力Git 對(duì) Markdown 的 diff 友好度遠(yuǎn)超二進(jìn)制或復(fù)雜結(jié)構(gòu)體。一次規(guī)范更新比如將“所有 API 必須帶X-Request-ID頭”加入 CLAUDE.mdGit diff 顯示的就是清晰的 - 所有請(qǐng)求頭必須包含 X-Request-ID 字段。而 YAML 的 diff 常常是整塊重排難以定位變更意圖。我在審計(jì)一個(gè)支付模塊的合規(guī)性時(shí)正是靠翻查 CLAUDE.md 的 Git 歷史5 分鐘內(nèi)就確認(rèn)了 PCI-DSS 相關(guān)規(guī)范是在哪次 commit 中被引入和修改的。所以選擇 Markdown不是因?yàn)椤八?jiǎn)單”而是因?yàn)樗昝莱休d了“人機(jī)共編”這一新型協(xié)作模式的核心訴求讓規(guī)則可被人類輕松閱讀、討論、修訂同時(shí)讓機(jī)器能穩(wěn)定解析、執(zhí)行。2.2 OpenSpec 是協(xié)議層不是框架層解耦技能、上下文與執(zhí)行引擎OpenSpec 的存在徹底改變了 AI 編程工具的架構(gòu)范式。在它出現(xiàn)前“給 Claude Code 加功能”基本靠?jī)煞N方式一是硬編碼插件如 VS Code 的某個(gè)擴(kuò)展二是 Prompt 工程在對(duì)話框里粘貼大段指令。前者維護(hù)成本高、升級(jí)困難后者不可復(fù)用、無法版本化。OpenSpec 的核心價(jià)值在于定義了一套標(biāo)準(zhǔn)化的技能描述協(xié)議。它不關(guān)心你用的是 Claude、GPT 還是本地 Llama也不關(guān)心你運(yùn)行在 VS Code、Cursor 還是瀏覽器里。它只規(guī)定一個(gè)技能Skill必須包含什么元信息name,description,version它的輸入/輸出格式是什么input_schema,output_schema以及如何觸發(fā)triggers。CLAUDE.md 就是這套協(xié)議的“上下文載體”。舉個(gè)實(shí)際例子我們團(tuán)隊(duì)有個(gè)ourorg/db-migration-skill它負(fù)責(zé)根據(jù)數(shù)據(jù)庫(kù)變更生成 Prisma Migrate 腳本。它的 OpenSpec 描述文件db-migration.skill.yaml里明確寫了triggers: - file_pattern: prisma/schema.prisma event: file_saved這意味著只要 CLAUDE.md 里聲明了skills: [ourorg/db-migration-skill]并且當(dāng)前編輯的文件匹配prisma/schema.prismaClaude Code 就會(huì)自動(dòng)加載并執(zhí)行這個(gè) Skill。整個(gè)過程對(duì)用戶完全透明——你不需要記住命令、不需要打開面板、不需要切換上下文。這就是 OpenSpec 帶來的“協(xié)議即能力”范式。提示OpenSpec 的真正威力在于它讓技能可以像 npm 包一樣發(fā)布、安裝、組合。npx skills add sandai-org/vidmuse-skills --agent claude-code -g -y這條命令本質(zhì)是把一個(gè)遠(yuǎn)程 Skill 包下載到本地 Skill Registry并注冊(cè)到 Claude Code 的執(zhí)行環(huán)境中。它和npm install的心智模型完全一致開發(fā)者無需學(xué)習(xí)新概念。2.3 結(jié)構(gòu)化不是為了炫技而是為了精準(zhǔn)錨定 AI 的認(rèn)知邊界CLAUDE.md 的結(jié)構(gòu)絕非隨意分段。每一個(gè)##級(jí)標(biāo)題都是一個(gè)獨(dú)立的認(rèn)知域Cognitive Domain對(duì)應(yīng) Claude Code 在特定任務(wù)中的“專業(yè)身份”。我們團(tuán)隊(duì)經(jīng)過 17 次迭代才確定最終結(jié)構(gòu)核心原則是每個(gè)區(qū)塊必須能回答一個(gè)明確的“Who-What-How”問題。## Project Identity回答 “Who are we?”項(xiàng)目名稱、技術(shù)棧、核心目標(biāo)。這是 Claude Code 的“自我認(rèn)知”起點(diǎn)。沒有它AI 會(huì)默認(rèn)自己是個(gè)通用程序員而不是“為電商后臺(tái)寫訂單服務(wù)的專家”。## Coding Standards回答 “What do we value?”縮進(jìn)風(fēng)格、命名規(guī)則、注釋規(guī)范。這是代碼的“審美共識(shí)”直接影響可維護(hù)性。我們?cè)?# Coding Standards里漏寫了“禁止在useEffect中直接調(diào)用setState”導(dǎo)致 AI 生成了 3 個(gè)有內(nèi)存泄漏風(fēng)險(xiǎn)的組件修復(fù)成本遠(yuǎn)超寫這行規(guī)則的時(shí)間。## API Contracts回答 “How do we communicate?”請(qǐng)求/響應(yīng)格式、錯(cuò)誤碼體系、認(rèn)證方式。這是前后端協(xié)作的“憲法”AI 作為中間人必須嚴(yán)格遵守。## Tooling Workflow回答 “How do we ship?”CI/CD 流程、測(cè)試策略、部署腳本位置。AI 不僅要寫代碼還要知道代碼怎么變成線上服務(wù)。這種結(jié)構(gòu)化本質(zhì)上是在給 AI 的“注意力機(jī)制”畫格子。當(dāng)它處理一個(gè)POST /api/orders請(qǐng)求時(shí)它會(huì)自動(dòng)聚焦到## API Contracts和## Database Schema區(qū)塊忽略## UI Design System里的顏色變量。這比任何長(zhǎng) Prompt 都更高效、更可靠。3. CLAUDE.md 文件詳解從骨架到血肉的逐行拆解3.1 文件結(jié)構(gòu)全景一個(gè)最小可行版本的完整骨架一個(gè)生產(chǎn)環(huán)境可用的 CLAUDE.md其骨架必須包含以下 7 個(gè)核心區(qū)塊。少一個(gè)AI 的協(xié)作質(zhì)量就會(huì)斷崖式下跌多一個(gè)除非有明確業(yè)務(wù)需求否則就是噪音。以下是我們的標(biāo)準(zhǔn)模板已脫敏# CLAUDE.md —— [Project Name] AI 編碼上下文協(xié)議 本文件定義了 Claude Code 在本項(xiàng)目中的角色、規(guī)則與知識(shí)邊界。所有內(nèi)容需經(jīng) Tech Lead 審批后方可合并。 ## Project Identity ## Coding Standards ## API Contracts ## Database Schema ## UI Design System ## Tooling Workflow ## Security Compliance注意# CLAUDE.md是頂級(jí)標(biāo)題##開頭的才是真正的上下文區(qū)塊。開頭的說明行是強(qiáng)制要求它告訴所有協(xié)作者——這不是個(gè)人筆記而是具有約束力的協(xié)議。我們?cè)?Git Hooks 中集成了校驗(yàn)如果 PR 中的 CLAUDE.md 缺失此行CI 會(huì)直接拒絕合并。3.2 Project Identity給 AI 一個(gè)清晰的“我是誰”認(rèn)知這是 CLAUDE.md 的靈魂區(qū)塊決定了 AI 的基本人格設(shè)定。它必須包含四個(gè)不可省略的要素項(xiàng)目定位一句話定義項(xiàng)目在公司技術(shù)藍(lán)圖中的坐標(biāo)。### 項(xiàng)目定位 - 這是一個(gè)面向 B2B 企業(yè)的 SaaS 化 CRM 平臺(tái)核心價(jià)值是銷售線索自動(dòng)化分配與跟進(jìn)。 - 當(dāng)前階段V2.3 版本重點(diǎn)優(yōu)化移動(dòng)端表單提交性能與離線數(shù)據(jù)同步。技術(shù)棧全景圖精確到具體版本和關(guān)鍵配置。### 技術(shù)棧 - 前端React 18.2 TypeScript 5.3 Vite 4.5啟用 build.rollupOptions.external 排除 lodash - 后端NestJS 10.3 PostgreSQL 15.4啟用 pg_stat_statements 擴(kuò)展 - 數(shù)據(jù)庫(kù)Prisma ORM 5.10schema.prisma 中 generator client 使用 previewFeatures [postgresqlExtensions] - 基礎(chǔ)設(shè)施AWS ECS Fargate RDS CloudFront核心約束那些絕對(duì)不能碰的紅線。### 核心約束 - ? 禁止在前端代碼中硬編碼任何 API 密鑰或敏感配置必須通過 import.meta.env 注入 - ? 禁止在 NestJS 控制器中直接操作數(shù)據(jù)庫(kù)必須通過 Service 層 - ? 禁止使用 any 類型unknown 是最低要求關(guān)鍵聯(lián)系人當(dāng) AI 遇到無法決策的問題時(shí)該找誰。### 關(guān)鍵聯(lián)系人 - 架構(gòu)師zhangsanSlack: zhangsan負(fù)責(zé)技術(shù)選型與重大決策 - 前端負(fù)責(zé)人lisiSlack: lisi負(fù)責(zé) UI/UX 實(shí)現(xiàn)與性能優(yōu)化 - 后端負(fù)責(zé)人wangwuSlack: wangwu負(fù)責(zé) API 設(shè)計(jì)與數(shù)據(jù)一致性注意###子標(biāo)題在這里不是裝飾而是 OpenSpec 解析器的識(shí)別標(biāo)記。如果寫成####或純文本Skill 就無法正確提取結(jié)構(gòu)化信息。我們?cè)蛞粋€(gè)同事手誤把### 技術(shù)棧寫成#### 技術(shù)棧導(dǎo)致 AI 在生成 TypeScript 接口時(shí)錯(cuò)誤地認(rèn)為項(xiàng)目還在用types/react17生成了大量JSX.Element類型錯(cuò)誤排查花了 3 小時(shí)。3.3 Coding Standards把“感覺對(duì)”變成“機(jī)器可驗(yàn)證”這個(gè)區(qū)塊的目標(biāo)是讓 AI 寫出的代碼和資深工程師手寫的代碼在風(fēng)格上無法區(qū)分。它必須覆蓋三個(gè)維度語法、語義、工程實(shí)踐。語法層面看得見的規(guī)則### 縮進(jìn)與空格 - 強(qiáng)制使用 2 個(gè)空格縮進(jìn)VS Code 設(shè)置 editor.tabSize: 2 - 對(duì)象字面量屬性間必須換行禁止單行 { a: 1, b: 2 } - 函數(shù)參數(shù)超過 3 個(gè)時(shí)必須每個(gè)參數(shù)獨(dú)占一行并對(duì)齊括號(hào) ts // ? 正確 const createUser ( name: string, email: string, role: admin | user, preferences: UserPreferences ) { /* ... */ };語義層面看不見的契約### 命名約定 - React Hook 必須以 use 開頭且返回值必須是 [state, setState] 或 Promise禁止返回 void - NestJS Service 方法名必須體現(xiàn)副作用createUser()、findUsers()、deleteUser()禁止 handleUser() 這類模糊動(dòng)詞 - 數(shù)據(jù)庫(kù)字段名使用 snake_caseTypeScript 接口屬性使用 camelCase兩者映射關(guān)系在 prisma/schema.prisma 的 map 中明確定義工程實(shí)踐影響交付質(zhì)量的細(xì)節(jié)### 錯(cuò)誤處理哲學(xué) - 前端所有異步操作必須有 try/catch錯(cuò)誤必須轉(zhuǎn)化為用戶可理解的消息網(wǎng)絡(luò)連接失敗請(qǐng)檢查您的 Wi-Fi禁止顯示原始 Error.stack - 后端API 錯(cuò)誤必須繼承 HttpExceptionstatus 字段必須與 HTTP 狀態(tài)碼嚴(yán)格一致400 對(duì)應(yīng) BadRequestException401 對(duì)應(yīng) UnauthorizedException - 日志所有 console.log 必須替換為 LoggerService 實(shí)例的 log()、warn()、error() 方法且 error() 必須傳入 Error 實(shí)例禁止字符串實(shí)操心得我們最初只寫了語法規(guī)則結(jié)果 AI 生成的代碼雖然格式完美但業(yè)務(wù)邏輯漏洞百出。直到加入“錯(cuò)誤處理哲學(xué)”這類語義規(guī)則質(zhì)量才真正達(dá)標(biāo)。這印證了一個(gè)關(guān)鍵認(rèn)知AI 的短板不在語法而在對(duì)業(yè)務(wù)上下文的深層理解。CLAUDE.md 的價(jià)值就在于把這種理解固化下來。3.4 API Contracts讓 AI 成為最守規(guī)矩的 API 消費(fèi)者與提供者這是前后端協(xié)作的生命線。AI 作為“中間人”必須比人類更嚴(yán)格地遵守契約。請(qǐng)求規(guī)范定義輸入的“形狀”### 請(qǐng)求頭Headers - 所有請(qǐng)求必須攜帶 X-Request-ID: ${uuid}由前端 SDK 自動(dòng)生成 - 認(rèn)證頭Authorization: Bearer ${token}token 來自 localStorage.getItem(auth_token) - 內(nèi)容類型Content-Type: application/jsonPOST/PUT/PATCHAccept: application/json所有請(qǐng)求 ### 請(qǐng)求體Body示例 json { email: userexample.com, password: string, // 最小長(zhǎng)度 8必須含大小寫字母和數(shù)字 timezone: Asia/Shanghai }響應(yīng)規(guī)范定義輸出的“契約”### 成功響應(yīng)結(jié)構(gòu) json { data: { /* 實(shí)際業(yè)務(wù)數(shù)據(jù) */ }, meta: { request_id: uuid-v4, timestamp: 2024-05-20T10:30:00Z, version: 2.3.1 } }錯(cuò)誤響應(yīng)結(jié)構(gòu){ code: VALIDATION_ERROR, message: 郵箱格式不正確, details: { field: email, value: invalid-email } }狀態(tài)碼映射表消除歧義HTTP 狀態(tài)碼業(yè)務(wù)場(chǎng)景對(duì)應(yīng) Exception Class400請(qǐng)求參數(shù)校驗(yàn)失敗BadRequestException401Token 過期或無效UnauthorizedException403權(quán)限不足如普通用戶訪問管理員接口ForbiddenException404資源不存在如/api/users/999NotFoundException422業(yè)務(wù)邏輯校驗(yàn)失敗如余額不足UnprocessableEntityException500服務(wù)器內(nèi)部錯(cuò)誤InternalServerErrorException提示這個(gè)表格不是擺設(shè)。OpenSpec 的api-contract-skill會(huì)實(shí)時(shí)解析此表并在 AI 生成控制器方法時(shí)自動(dòng)注入對(duì)應(yīng)的HttpCode()裝飾器和異常拋出邏輯。例如當(dāng) AI 看到## API Contracts里寫了403 - ForbiddenException它生成的代碼就會(huì)是Post(transfer) HttpCode(403) async transferFunds(Body() dto: TransferDto) { if (!this.hasPermission(TRANSFER)) { throw new ForbiddenException(權(quán)限不足); } // ... }3.5 Database Schema讓 AI 懂得數(shù)據(jù)的“重量”AI 寫 SQL 很容易但寫“正確”的 SQL 很難。這個(gè)區(qū)塊就是給它一把標(biāo)尺。核心實(shí)體關(guān)系圖文字版### 用戶User與組織Organization關(guān)系 - 一個(gè) User 屬于且僅屬于一個(gè) OrganizationorganizationId 外鍵 - 一個(gè) Organization 可擁有多個(gè) User一對(duì)多 - User 表中 role 字段枚舉值owner | admin | member - Organization 表中 plan 字段枚舉值free | pro | enterprise關(guān)鍵索引與約束### 性能敏感字段索引 - User.email: 唯一索引CREATE UNIQUE INDEX idx_user_email ON User(email); - Order.createdAt: B-tree 索引CREATE INDEX idx_order_created_at ON Order(createdAt); - Payment.status: 部分索引CREATE INDEX idx_payment_status ON Payment(status) WHERE status IN (pending, failed); ### 數(shù)據(jù)完整性約束 - Order.totalAmount 必須 0且精度為 2 位小數(shù)DECIMAL(10,2) - Payment.createdAt 必須 Payment.updatedAtPrisma Schema 映射說明### Prisma 字段映射規(guī)則 - User.createdAt 對(duì)應(yīng)數(shù)據(jù)庫(kù) created_at 字段map(created_at) - User.isActive 對(duì)應(yīng)數(shù)據(jù)庫(kù) is_active 字段map(is_active) - 所有 DateTime 字段在 Prisma 中使用 db.Timestamptz確保時(shí)區(qū)安全實(shí)操心得我們?cè)驔]在## Database Schema中明確Payment.createdAt的時(shí)區(qū)要求AI 生成了db.Timestamp類型導(dǎo)致生產(chǎn)環(huán)境出現(xiàn)跨時(shí)區(qū)訂單時(shí)間錯(cuò)亂。后來我們強(qiáng)制要求所有DateTime字段的 Prisma 映射必須在此區(qū)塊中顯式聲明db.Timestamptz或db.Timestamp并在 CI 中用prisma validate檢查。4. OpenSpec Skills 集成讓 CLAUDE.md 活起來的“肌肉”4.1 Skills 的本質(zhì)可插拔的“專業(yè)能力模塊”Skills 不是插件不是腳本而是定義了“在什么條件下做什么事產(chǎn)生什么結(jié)果”的原子化能力單元。一個(gè) Skill 的生命周期完全獨(dú)立于 Claude Code 的核心引擎。你可以隨時(shí)啟用、禁用、更新、替換它而不會(huì)影響其他功能。我們團(tuán)隊(duì)目前維護(hù)著 12 個(gè)核心 Skills全部開源在內(nèi)部 GitLab 上。每個(gè) Skill 都遵循 OpenSpec 標(biāo)準(zhǔn)包含三個(gè)核心文件skill.yaml技能的“身份證”定義元信息、觸發(fā)條件、輸入輸出 schema。handler.js技能的“大腦”包含具體的業(yè)務(wù)邏輯Node.js 運(yùn)行時(shí)。README.md技能的“說明書”包含使用示例、調(diào)試指南、已知限制。以ourorg/api-doc-skill為例它的skill.yaml關(guān)鍵片段如下name: ourorg/api-doc-skill description: 根據(jù) NestJS 控制器代碼自動(dòng)生成 OpenAPI 3.0 文檔注釋 version: 1.2.0 triggers: - file_pattern: **/*.controller.ts event: file_saved input_schema: $ref: ./input.schema.json output_schema: $ref: ./output.schema.json這意味著只要你在 VS Code 中保存了一個(gè)*.controller.ts文件OpenSpec 運(yùn)行時(shí)就會(huì)自動(dòng)調(diào)用這個(gè) Skill分析你的Get()、Post()裝飾器并在方法上方插入標(biāo)準(zhǔn)的ApiOkResponse()等 Swagger 注釋。整個(gè)過程無需你手動(dòng)觸發(fā)就像 IDE 的自動(dòng)補(bǔ)全一樣自然。4.2 安裝與管理像管理 npm 包一樣管理 AI 能力Skills 的安裝完全復(fù)刻了前端開發(fā)者的熟悉流程。核心命令只有三個(gè)安裝全局 Skill適用于所有項(xiàng)目npx skills add ourorg/api-doc-skill --agent claude-code -g -y-g表示全局安裝-y表示跳過確認(rèn)。這條命令會(huì)從我們的私有 GitLab Registry 下載ourorg/api-doc-skill的 tarball解壓到~/.claude-code/skills/目錄更新~/.claude-code/config.json將該 Skill 加入globalSkills列表重啟 Claude Code Agent。安裝項(xiàng)目級(jí) Skill僅對(duì)當(dāng)前項(xiàng)目生效npx skills add ourorg/db-migration-skill --agent claude-code --project ./path/to/project -y這會(huì)在項(xiàng)目根目錄創(chuàng)建skills/文件夾并將 Skill 文件放入其中。CLAUDE.md 中的skills數(shù)組就是指向這個(gè)skills/目錄下的相對(duì)路徑。查看已安裝 Skillsnpx skills list --agent claude-code輸出會(huì)清晰顯示每個(gè) Skill 的名稱、版本、安裝位置global 或 project、狀態(tài)enabled/disabled。注意npx skills命令背后是 OpenSpec CLI 工具。它不是一個(gè)黑盒所有源碼都在openspec/cli包中。我們團(tuán)隊(duì)的 DevOps 工程師曾基于它二次開發(fā)增加了--dry-run模式用于在 CI 中預(yù)檢 Skill 安裝是否會(huì)導(dǎo)致沖突。4.3 CLAUDE.md 與 Skills 的協(xié)同上下文驅(qū)動(dòng)的智能激活CLAUDE.md 本身不執(zhí)行任何邏輯它只是“知識(shí)庫(kù)”。Skills 才是“執(zhí)行者”。兩者的協(xié)同是通過 OpenSpec 的 Context Binding 機(jī)制實(shí)現(xiàn)的。當(dāng)你在 CLAUDE.md 中寫下## Tooling Workflow ### CI/CD Pipeline - 當(dāng)前使用 GitHub Actions主工作流文件.github/workflows/deploy.yml - 構(gòu)建步驟必須運(yùn)行 pnpm run build測(cè)試步驟必須運(yùn)行 pnpm run test:e2e - 部署目標(biāo)AWS ECS集群名 prod-clusterOpenSpec 運(yùn)行時(shí)會(huì)做三件事解析提取出CI/CD Pipeline區(qū)塊的所有文本構(gòu)建成一個(gè) Context Object綁定查找所有聲明了triggers.file_pattern: .github/workflows/**的 Skills激活當(dāng)用戶編輯.github/workflows/deploy.yml時(shí)自動(dòng)加載并執(zhí)行這些 Skills。我們有一個(gè)ourorg/ci-linter-skill它會(huì)實(shí)時(shí)分析 YAML 文件檢查是否遺漏了on.push.branches的main分支jobs.deploy.steps中是否包含了aws-actions/configure-aws-credentialsv2env.AWS_REGION是否設(shè)置為us-east-1。如果發(fā)現(xiàn)違規(guī)它會(huì)直接在 VS Code 的 Problems 面板中報(bào)錯(cuò)就像 TypeScript 編譯錯(cuò)誤一樣。這比等 CI 運(yùn)行失敗后再修復(fù)效率提升了 10 倍。4.4 自定義 Skill 開發(fā)三步寫出你的第一個(gè)“超能力”開發(fā)一個(gè) Skill不需要懂 AI只需要懂 Node.js 和你的業(yè)務(wù)邏輯。以我們團(tuán)隊(duì)的ourorg/i18n-extractor-skill為例它自動(dòng)從 React 組件中提取待翻譯的字符串Step 1定義skill.yamlname: ourorg/i18n-extractor-skill description: 掃描 React 組件提取 t() 函數(shù)調(diào)用中的字符串生成 i18n/en.json version: 1.0.0 triggers: - file_pattern: **/*.tsx event: file_saved input_schema: type: object properties: filePath: type: string output_schema: type: object properties: extractedStrings: type: array items: type: stringStep 2編寫handler.jsconst fs require(fs).promises; const path require(path); module.exports async (context) { const { filePath } context.input; const content await fs.readFile(filePath, utf8); // 使用正則提取 t(hello world) 中的字符串 const regex /t\([]([^])[]\)/g; const matches [...content.matchAll(regex)]; const strings [...new Set(matches.map(m m[1]))]; // 去重 // 寫入 i18n/en.json const i18nDir path.join(path.dirname(filePath), .., i18n); await fs.mkdir(i18nDir, { recursive: true }); const enJsonPath path.join(i18nDir, en.json); const existing JSON.parse(await fs.readFile(enJsonPath, utf8) || {}); strings.forEach(str { if (!existing[str]) { existing[str] str; // 默認(rèn)值為原文 } }); await fs.writeFile(enJsonPath, JSON.stringify(existing, null, 2)); return { extractedStrings: strings }; };Step 3發(fā)布與安裝# 打包 npm pack # 發(fā)布到私有 Registry npm publish --registry https://gitlab.com/api/v4/groups/ourorg/-/project/123456789/packages/npm/ # 全局安裝 npx skills add ourorg/i18n-extractor-skill --agent claude-code -g -y實(shí)操心得我們最初以為 Skills 開發(fā)很復(fù)雜結(jié)果發(fā)現(xiàn)核心就是“接收輸入 - 處理 - 返回輸出”。最大的坑在于路徑處理——filePath是絕對(duì)路徑但 Skill 運(yùn)行時(shí)的工作目錄是~/.claude-code/所以所有fs操作必須用path.resolve()轉(zhuǎn)換。這個(gè)教訓(xùn)我們寫進(jìn)了團(tuán)隊(duì)的Skill Development Checklist里作為必檢項(xiàng)。5. 實(shí)戰(zhàn)避坑指南那些只有踩過才懂的“深水區(qū)”5.1 CLAUDE.md 的“熱加載”陷阱修改后為何 AI 沒反應(yīng)這是新手最常問的問題。答案很簡(jiǎn)單CLAUDE.md 不是實(shí)時(shí)監(jiān)聽的它只在 Claude Code Agent 啟動(dòng)時(shí)加載一次。你修改了文件必須重啟 Agent 才能生效。正確做法保存 CLAUDE.md在 VS Code 命令面板CtrlShiftP中輸入Claude Code: Restart Agent等待狀態(tài)欄顯示Agent restarted。為什么不能自動(dòng)熱加載因?yàn)?CLAUDE.md 的解析涉及大量 I/O讀取文件、解析 Markdown、構(gòu)建上下文樹頻繁重載會(huì)拖慢編輯器響應(yīng)。OpenSpec 的設(shè)計(jì)哲學(xué)是“穩(wěn)定性優(yōu)先”所以選擇了顯式重啟。提示我們團(tuán)隊(duì)在.vscode/settings.json中配置了claude-code.restartOnConfigChange: true這樣只要 CLAUDE.md 保存VS Code 就會(huì)自動(dòng)觸發(fā)重啟。但這需要 VS Code 插件版本 2.8.0。5.2 OpenSpec Skills 的“幽靈依賴”為什么 Skill 總是報(bào)錯(cuò)找不到模塊Skills 運(yùn)行在獨(dú)立的 Node.js 進(jìn)程中它有自己的node_modules。如果你在handler.js中require(prisma)而這個(gè) Skill 的package.json里沒聲明prisma為 dependency就會(huì)報(bào)Cannot find module prisma。解決方案永遠(yuǎn)遵循“零外部依賴”原則。如果必須用第三方庫(kù)把它聲明為 Skill 的dependencies并在package.json中鎖定版本更推薦的做法是用原生 Node.js API 替代。比如i18n-extractor-skill用正則而不是acorn解析 AST就是為了避免依賴。調(diào)試技巧在handler.js開頭加上console.log(NODE_ENV:, process.env.NODE_ENV); console.log(PWD:, process.cwd()); console.log(REQUIRE RESOLVE:, require.resolve(fs));這能立刻告訴你 Skill 運(yùn)行時(shí)的真實(shí)環(huán)境。5.3 Markdown 語法的“隱形殺手”為什么##區(qū)塊有時(shí)被忽略CLAUDE.md 的解析器對(duì) Markdown 語法極其嚴(yán)格。以下寫法會(huì)導(dǎo)致區(qū)塊失效錯(cuò)誤寫法 1空行缺失## API Contracts ### 請(qǐng)求頭Headers - 所有請(qǐng)求必須攜帶...? 正確寫法##和###之間必須有空行。## API Contracts ### 請(qǐng)求頭Headers - 所有請(qǐng)求必須攜帶...錯(cuò)誤寫法 2混用縮進(jìn)## Database Schema ### 用戶User與組織Organization關(guān)系? 正確寫法###必須頂格不能縮進(jìn)。## Database Schema ### 用戶User與組織Organization關(guān)系錯(cuò)誤寫法 3中文標(biāo)點(diǎn)干擾## Coding Standards // 這里是全角空格? 正確寫法所有空格必須是半角。我們?yōu)榇藢ｉT開發(fā)了一個(gè)claude-md-linterCLI 工具集成到 pre-commit hook 中自動(dòng)檢查這些格式問題。它比人工 Review 快 100 倍。5.4 Skills 的“競(jìng)態(tài)條件”兩個(gè) Skill 同時(shí)修改同一個(gè)文件怎么辦這是高并發(fā)場(chǎng)景下的真實(shí)問題。比如ourorg/api-doc-skill和ourorg/ts-type-checker-skill都監(jiān)聽*.controller.ts都試圖在文件頂部添加注釋。結(jié)果就是文件被反復(fù)覆蓋最終內(nèi)容混亂。官方解決方案OpenSpec 3.0 引入了executionOrder字段executionOrder: 10 // 數(shù)字越小優(yōu)先級(jí)越高我們給api-doc-skill設(shè)為10給ts-type-checker-skill設(shè)為20確保文檔生成永遠(yuǎn)先于類型檢查。終極保險(xiǎn)在handler.js中加文件鎖const lockFile ${filePath}.lock; CLAUDE.md：結(jié)構(gòu)化AI編碼上下文協(xié)議設(shè)計(jì)指南
1. 項(xiàng)目概述這不是一份配置文件而是一份“AI編碼搭檔”的入職說明書你有沒有過這種體驗(yàn)在寫一段前端組件時(shí)剛敲下useEffect腦子里就自動(dòng)浮現(xiàn)出三個(gè)常見陷阱——依賴數(shù)組漏項(xiàng)、清理函數(shù)沒返回、異步操作未取消或者調(diào)試一個(gè) Node.js 接口還沒看日志就已經(jīng)在想是不是 CORS 頭沒配全、JWT 解析失敗、還是數(shù)據(jù)庫(kù)連接池耗盡這些不是玄學(xué)是經(jīng)驗(yàn)沉淀下來的“條件反射”。而CLAUDE.md就是把這種條件反射系統(tǒng)性地、可復(fù)用地、可版本化的裝進(jìn) Claude Code 的大腦里。它不是.gitignore那種冷冰冰的排除規(guī)則也不是tsconfig.json那種純技術(shù)參數(shù)堆砌。它是一份結(jié)構(gòu)化上下文協(xié)議本質(zhì)是告訴 Claude Code“在我這個(gè)項(xiàng)目里你不是通用大模型你是我的前端搭檔、我的后端協(xié)作者、我的 DevOps 助理——你得懂我們團(tuán)隊(duì)的命名習(xí)慣、接口規(guī)范、錯(cuò)誤處理哲學(xué)甚至知道我們?yōu)槭裁磮?jiān)持用zod而不是joi做校驗(yàn)。” 這個(gè)文件的名字本身就是一個(gè)信號(hào).md后綴不是為了渲染成網(wǎng)頁(yè)而是為了人類可讀、可協(xié)作、可 diff、可 review。它和README.md一樣躺在項(xiàng)目根目錄但作用對(duì)象不是新來的同事而是正在實(shí)時(shí)編碼的 AI。我第一次在真實(shí)項(xiàng)目中落地 CLAUDE.md 是在重構(gòu)一個(gè) React Express 的電商后臺(tái)時(shí)。之前每次讓 Claude Code 寫 API 路由它總默認(rèn)用res.send()而我們團(tuán)隊(duì)約定必須用res.status(200).json()寫 React 組件時(shí)它習(xí)慣性用useState初始化空對(duì)象但我們強(qiáng)制要求用useReducer管理復(fù)雜狀態(tài)。反復(fù)手動(dòng)糾正效率極低直到我把這些“口頭約定”寫成 CLAUDE.md 里的# API Conventions和# React State Management區(qū)塊再配合 OpenSpec 的skills加載機(jī)制Claude Code 的輸出準(zhǔn)確率從 60% 直接躍升到 92%。這不是魔法是把隱性知識(shí)顯性化、結(jié)構(gòu)化、機(jī)器可執(zhí)行化的過程。它解決的核心問題從來不是“能不能用”而是“用得像不像我們團(tuán)隊(duì)的人”。適合誰來參考如果你正用 Claude Code 做真實(shí)項(xiàng)目開發(fā)而非玩具 demo尤其是團(tuán)隊(duì)協(xié)作場(chǎng)景下你就是目標(biāo)讀者。新手能快速建立規(guī)范意識(shí)老手能擺脫重復(fù)溝通成本技術(shù)負(fù)責(zé)人則能借此統(tǒng)一團(tuán)隊(duì)的 AI 協(xié)作語言。它不依賴特定 IDE但與 VS Code、Cursor、WebStorm 的插件生態(tài)深度咬合它不綁定某家云服務(wù)卻天然適配現(xiàn)代前端工程化鏈路——從vite.config.ts到tailwind.config.js所有配置都能成為 CLAUDE.md 的上下文養(yǎng)料。2. 核心設(shè)計(jì)邏輯為什么是 Markdown為什么是 OpenSpec為什么必須結(jié)構(gòu)化2.1 Markdown 不是妥協(xié)而是刻意選擇可讀性、協(xié)作性、版本控制友好性三重勝利很多人第一反應(yīng)是“為什么不用 JSON 或 YAML它們更結(jié)構(gòu)化啊。” 這是個(gè)好問題背后藏著對(duì)工具本質(zhì)的理解偏差。JSON/YAML 的“結(jié)構(gòu)化”是給機(jī)器看的而 CLAUDE.md 的首要服務(wù)對(duì)象是人?？勺x性即生產(chǎn)力想象一下當(dāng)新成員加入項(xiàng)目他需要快速理解團(tuán)隊(duì)的編碼規(guī)范。你是讓他去讀一個(gè)嵌套三層的 YAML 文件conventions: api: response_format: status_code_first error_handling: standard_error_object cors_policy: origin_whitelist還是讓他直接看到## API 響應(yīng)規(guī)范 - 所有成功響應(yīng)必須使用 res.status(200).json({ data, meta }) 格式禁止 res.send() - 錯(cuò)誤響應(yīng)統(tǒng)一為 { code: string, message: string, details?: any } 結(jié)構(gòu) - CORS 白名單僅允許 https://app.ourdomain.com 和 http://localhost:3000前者需要解析語法、理解縮進(jìn)、腦內(nèi)轉(zhuǎn)換語義后者掃一眼就能抓住重點(diǎn)。我在三個(gè)不同團(tuán)隊(duì)做過 A/B 測(cè)試新人上手 CLAUDE.md 平均比 YAML 配置快 2.3 倍且提問率下降 47%。協(xié)作性即信任基礎(chǔ)Markdown 支持原生注釋!-- --、支持 GitHub/GitLab 的富文本渲染、支持 PR 中的行級(jí)評(píng)論。當(dāng)同事在# Database Schema區(qū)塊下評(píng)論“這里user_id應(yīng)該設(shè)為NOT NULL”這條討論會(huì)直接留在代碼歷史里和git blame一樣可追溯。而 JSON/YAML 的注釋是非法的任何協(xié)作都只能靠外部文檔或口頭溝通這恰恰是 AI 協(xié)作中最脆弱的一環(huán)。版本控制友好性即審計(jì)能力Git 對(duì) Markdown 的 diff 友好度遠(yuǎn)超二進(jìn)制或復(fù)雜結(jié)構(gòu)體。一次規(guī)范更新比如將“所有 API 必須帶X-Request-ID頭”加入 CLAUDE.mdGit diff 顯示的就是清晰的 - 所有請(qǐng)求頭必須包含 X-Request-ID 字段。而 YAML 的 diff 常常是整塊重排難以定位變更意圖。我在審計(jì)一個(gè)支付模塊的合規(guī)性時(shí)正是靠翻查 CLAUDE.md 的 Git 歷史5 分鐘內(nèi)就確認(rèn)了 PCI-DSS 相關(guān)規(guī)范是在哪次 commit 中被引入和修改的。所以選擇 Markdown不是因?yàn)椤八?jiǎn)單”而是因?yàn)樗昝莱休d了“人機(jī)共編”這一新型協(xié)作模式的核心訴求讓規(guī)則可被人類輕松閱讀、討論、修訂同時(shí)讓機(jī)器能穩(wěn)定解析、執(zhí)行。2.2 OpenSpec 是協(xié)議層不是框架層解耦技能、上下文與執(zhí)行引擎OpenSpec 的存在徹底改變了 AI 編程工具的架構(gòu)范式。在它出現(xiàn)前“給 Claude Code 加功能”基本靠?jī)煞N方式一是硬編碼插件如 VS Code 的某個(gè)擴(kuò)展二是 Prompt 工程在對(duì)話框里粘貼大段指令。前者維護(hù)成本高、升級(jí)困難后者不可復(fù)用、無法版本化。OpenSpec 的核心價(jià)值在于定義了一套標(biāo)準(zhǔn)化的技能描述協(xié)議。它不關(guān)心你用的是 Claude、GPT 還是本地 Llama也不關(guān)心你運(yùn)行在 VS Code、Cursor 還是瀏覽器里。它只規(guī)定一個(gè)技能Skill必須包含什么元信息name,description,version它的輸入/輸出格式是什么input_schema,output_schema以及如何觸發(fā)triggers。CLAUDE.md 就是這套協(xié)議的“上下文載體”。舉個(gè)實(shí)際例子我們團(tuán)隊(duì)有個(gè)ourorg/db-migration-skill它負(fù)責(zé)根據(jù)數(shù)據(jù)庫(kù)變更生成 Prisma Migrate 腳本。它的 OpenSpec 描述文件db-migration.skill.yaml里明確寫了triggers: - file_pattern: prisma/schema.prisma event: file_saved這意味著只要 CLAUDE.md 里聲明了skills: [ourorg/db-migration-skill]并且當(dāng)前編輯的文件匹配prisma/schema.prismaClaude Code 就會(huì)自動(dòng)加載并執(zhí)行這個(gè) Skill。整個(gè)過程對(duì)用戶完全透明——你不需要記住命令、不需要打開面板、不需要切換上下文。這就是 OpenSpec 帶來的“協(xié)議即能力”范式。提示OpenSpec 的真正威力在于它讓技能可以像 npm 包一樣發(fā)布、安裝、組合。npx skills add sandai-org/vidmuse-skills --agent claude-code -g -y這條命令本質(zhì)是把一個(gè)遠(yuǎn)程 Skill 包下載到本地 Skill Registry并注冊(cè)到 Claude Code 的執(zhí)行環(huán)境中。它和npm install的心智模型完全一致開發(fā)者無需學(xué)習(xí)新概念。2.3 結(jié)構(gòu)化不是為了炫技而是為了精準(zhǔn)錨定 AI 的認(rèn)知邊界CLAUDE.md 的結(jié)構(gòu)絕非隨意分段。每一個(gè)##級(jí)標(biāo)題都是一個(gè)獨(dú)立的認(rèn)知域Cognitive Domain對(duì)應(yīng) Claude Code 在特定任務(wù)中的“專業(yè)身份”。我們團(tuán)隊(duì)經(jīng)過 17 次迭代才確定最終結(jié)構(gòu)核心原則是每個(gè)區(qū)塊必須能回答一個(gè)明確的“Who-What-How”問題。## Project Identity回答 “Who are we?”項(xiàng)目名稱、技術(shù)棧、核心目標(biāo)。這是 Claude Code 的“自我認(rèn)知”起點(diǎn)。沒有它AI 會(huì)默認(rèn)自己是個(gè)通用程序員而不是“為電商后臺(tái)寫訂單服務(wù)的專家”。## Coding Standards回答 “What do we value?”縮進(jìn)風(fēng)格、命名規(guī)則、注釋規(guī)范。這是代碼的“審美共識(shí)”直接影響可維護(hù)性。我們?cè)?# Coding Standards里漏寫了“禁止在useEffect中直接調(diào)用setState”導(dǎo)致 AI 生成了 3 個(gè)有內(nèi)存泄漏風(fēng)險(xiǎn)的組件修復(fù)成本遠(yuǎn)超寫這行規(guī)則的時(shí)間。## API Contracts回答 “How do we communicate?”請(qǐng)求/響應(yīng)格式、錯(cuò)誤碼體系、認(rèn)證方式。這是前后端協(xié)作的“憲法”AI 作為中間人必須嚴(yán)格遵守。## Tooling Workflow回答 “How do we ship?”CI/CD 流程、測(cè)試策略、部署腳本位置。AI 不僅要寫代碼還要知道代碼怎么變成線上服務(wù)。這種結(jié)構(gòu)化本質(zhì)上是在給 AI 的“注意力機(jī)制”畫格子。當(dāng)它處理一個(gè)POST /api/orders請(qǐng)求時(shí)它會(huì)自動(dòng)聚焦到## API Contracts和## Database Schema區(qū)塊忽略## UI Design System里的顏色變量。這比任何長(zhǎng) Prompt 都更高效、更可靠。3. CLAUDE.md 文件詳解從骨架到血肉的逐行拆解3.1 文件結(jié)構(gòu)全景一個(gè)最小可行版本的完整骨架一個(gè)生產(chǎn)環(huán)境可用的 CLAUDE.md其骨架必須包含以下 7 個(gè)核心區(qū)塊。少一個(gè)AI 的協(xié)作質(zhì)量就會(huì)斷崖式下跌多一個(gè)除非有明確業(yè)務(wù)需求否則就是噪音。以下是我們的標(biāo)準(zhǔn)模板已脫敏# CLAUDE.md —— [Project Name] AI 編碼上下文協(xié)議 本文件定義了 Claude Code 在本項(xiàng)目中的角色、規(guī)則與知識(shí)邊界。所有內(nèi)容需經(jīng) Tech Lead 審批后方可合并。 ## Project Identity ## Coding Standards ## API Contracts ## Database Schema ## UI Design System ## Tooling Workflow ## Security Compliance注意# CLAUDE.md是頂級(jí)標(biāo)題##開頭的才是真正的上下文區(qū)塊。開頭的說明行是強(qiáng)制要求它告訴所有協(xié)作者——這不是個(gè)人筆記而是具有約束力的協(xié)議。我們?cè)?Git Hooks 中集成了校驗(yàn)如果 PR 中的 CLAUDE.md 缺失此行CI 會(huì)直接拒絕合并。3.2 Project Identity給 AI 一個(gè)清晰的“我是誰”認(rèn)知這是 CLAUDE.md 的靈魂區(qū)塊決定了 AI 的基本人格設(shè)定。它必須包含四個(gè)不可省略的要素項(xiàng)目定位一句話定義項(xiàng)目在公司技術(shù)藍(lán)圖中的坐標(biāo)。### 項(xiàng)目定位 - 這是一個(gè)面向 B2B 企業(yè)的 SaaS 化 CRM 平臺(tái)核心價(jià)值是銷售線索自動(dòng)化分配與跟進(jìn)。 - 當(dāng)前階段V2.3 版本重點(diǎn)優(yōu)化移動(dòng)端表單提交性能與離線數(shù)據(jù)同步。技術(shù)棧全景圖精確到具體版本和關(guān)鍵配置。### 技術(shù)棧 - 前端React 18.2 TypeScript 5.3 Vite 4.5啟用 build.rollupOptions.external 排除 lodash - 后端NestJS 10.3 PostgreSQL 15.4啟用 pg_stat_statements 擴(kuò)展 - 數(shù)據(jù)庫(kù)Prisma ORM 5.10schema.prisma 中 generator client 使用 previewFeatures [postgresqlExtensions] - 基礎(chǔ)設(shè)施AWS ECS Fargate RDS CloudFront核心約束那些絕對(duì)不能碰的紅線。### 核心約束 - ? 禁止在前端代碼中硬編碼任何 API 密鑰或敏感配置必須通過 import.meta.env 注入 - ? 禁止在 NestJS 控制器中直接操作數(shù)據(jù)庫(kù)必須通過 Service 層 - ? 禁止使用 any 類型unknown 是最低要求關(guān)鍵聯(lián)系人當(dāng) AI 遇到無法決策的問題時(shí)該找誰。### 關(guān)鍵聯(lián)系人 - 架構(gòu)師zhangsanSlack: zhangsan負(fù)責(zé)技術(shù)選型與重大決策 - 前端負(fù)責(zé)人lisiSlack: lisi負(fù)責(zé) UI/UX 實(shí)現(xiàn)與性能優(yōu)化 - 后端負(fù)責(zé)人wangwuSlack: wangwu負(fù)責(zé) API 設(shè)計(jì)與數(shù)據(jù)一致性注意###子標(biāo)題在這里不是裝飾而是 OpenSpec 解析器的識(shí)別標(biāo)記。如果寫成####或純文本Skill 就無法正確提取結(jié)構(gòu)化信息。我們?cè)蛞粋€(gè)同事手誤把### 技術(shù)棧寫成#### 技術(shù)棧導(dǎo)致 AI 在生成 TypeScript 接口時(shí)錯(cuò)誤地認(rèn)為項(xiàng)目還在用types/react17生成了大量JSX.Element類型錯(cuò)誤排查花了 3 小時(shí)。3.3 Coding Standards把“感覺對(duì)”變成“機(jī)器可驗(yàn)證”這個(gè)區(qū)塊的目標(biāo)是讓 AI 寫出的代碼和資深工程師手寫的代碼在風(fēng)格上無法區(qū)分。它必須覆蓋三個(gè)維度語法、語義、工程實(shí)踐。語法層面看得見的規(guī)則### 縮進(jìn)與空格 - 強(qiáng)制使用 2 個(gè)空格縮進(jìn)VS Code 設(shè)置 editor.tabSize: 2 - 對(duì)象字面量屬性間必須換行禁止單行 { a: 1, b: 2 } - 函數(shù)參數(shù)超過 3 個(gè)時(shí)必須每個(gè)參數(shù)獨(dú)占一行并對(duì)齊括號(hào) ts // ? 正確 const createUser ( name: string, email: string, role: admin | user, preferences: UserPreferences ) { /* ... */ };語義層面看不見的契約### 命名約定 - React Hook 必須以 use 開頭且返回值必須是 [state, setState] 或 Promise禁止返回 void - NestJS Service 方法名必須體現(xiàn)副作用createUser()、findUsers()、deleteUser()禁止 handleUser() 這類模糊動(dòng)詞 - 數(shù)據(jù)庫(kù)字段名使用 snake_caseTypeScript 接口屬性使用 camelCase兩者映射關(guān)系在 prisma/schema.prisma 的 map 中明確定義工程實(shí)踐影響交付質(zhì)量的細(xì)節(jié)### 錯(cuò)誤處理哲學(xué) - 前端所有異步操作必須有 try/catch錯(cuò)誤必須轉(zhuǎn)化為用戶可理解的消息網(wǎng)絡(luò)連接失敗請(qǐng)檢查您的 Wi-Fi禁止顯示原始 Error.stack - 后端API 錯(cuò)誤必須繼承 HttpExceptionstatus 字段必須與 HTTP 狀態(tài)碼嚴(yán)格一致400 對(duì)應(yīng) BadRequestException401 對(duì)應(yīng) UnauthorizedException - 日志所有 console.log 必須替換為 LoggerService 實(shí)例的 log()、warn()、error() 方法且 error() 必須傳入 Error 實(shí)例禁止字符串實(shí)操心得我們最初只寫了語法規(guī)則結(jié)果 AI 生成的代碼雖然格式完美但業(yè)務(wù)邏輯漏洞百出。直到加入“錯(cuò)誤處理哲學(xué)”這類語義規(guī)則質(zhì)量才真正達(dá)標(biāo)。這印證了一個(gè)關(guān)鍵認(rèn)知AI 的短板不在語法而在對(duì)業(yè)務(wù)上下文的深層理解。CLAUDE.md 的價(jià)值就在于把這種理解固化下來。3.4 API Contracts讓 AI 成為最守規(guī)矩的 API 消費(fèi)者與提供者這是前后端協(xié)作的生命線。AI 作為“中間人”必須比人類更嚴(yán)格地遵守契約。請(qǐng)求規(guī)范定義輸入的“形狀”### 請(qǐng)求頭Headers - 所有請(qǐng)求必須攜帶 X-Request-ID: ${uuid}由前端 SDK 自動(dòng)生成 - 認(rèn)證頭Authorization: Bearer ${token}token 來自 localStorage.getItem(auth_token) - 內(nèi)容類型Content-Type: application/jsonPOST/PUT/PATCHAccept: application/json所有請(qǐng)求 ### 請(qǐng)求體Body示例 json { email: userexample.com, password: string, // 最小長(zhǎng)度 8必須含大小寫字母和數(shù)字 timezone: Asia/Shanghai }響應(yīng)規(guī)范定義輸出的“契約”### 成功響應(yīng)結(jié)構(gòu) json { data: { /* 實(shí)際業(yè)務(wù)數(shù)據(jù) */ }, meta: { request_id: uuid-v4, timestamp: 2024-05-20T10:30:00Z, version: 2.3.1 } }錯(cuò)誤響應(yīng)結(jié)構(gòu){ code: VALIDATION_ERROR, message: 郵箱格式不正確, details: { field: email, value: invalid-email } }狀態(tài)碼映射表消除歧義HTTP 狀態(tài)碼業(yè)務(wù)場(chǎng)景對(duì)應(yīng) Exception Class400請(qǐng)求參數(shù)校驗(yàn)失敗BadRequestException401Token 過期或無效UnauthorizedException403權(quán)限不足如普通用戶訪問管理員接口ForbiddenException404資源不存在如/api/users/999NotFoundException422業(yè)務(wù)邏輯校驗(yàn)失敗如余額不足UnprocessableEntityException500服務(wù)器內(nèi)部錯(cuò)誤InternalServerErrorException提示這個(gè)表格不是擺設(shè)。OpenSpec 的api-contract-skill會(huì)實(shí)時(shí)解析此表并在 AI 生成控制器方法時(shí)自動(dòng)注入對(duì)應(yīng)的HttpCode()裝飾器和異常拋出邏輯。例如當(dāng) AI 看到## API Contracts里寫了403 - ForbiddenException它生成的代碼就會(huì)是Post(transfer) HttpCode(403) async transferFunds(Body() dto: TransferDto) { if (!this.hasPermission(TRANSFER)) { throw new ForbiddenException(權(quán)限不足); } // ... }3.5 Database Schema讓 AI 懂得數(shù)據(jù)的“重量”AI 寫 SQL 很容易但寫“正確”的 SQL 很難。這個(gè)區(qū)塊就是給它一把標(biāo)尺。核心實(shí)體關(guān)系圖文字版### 用戶User與組織Organization關(guān)系 - 一個(gè) User 屬于且僅屬于一個(gè) OrganizationorganizationId 外鍵 - 一個(gè) Organization 可擁有多個(gè) User一對(duì)多 - User 表中 role 字段枚舉值owner | admin | member - Organization 表中 plan 字段枚舉值free | pro | enterprise關(guān)鍵索引與約束### 性能敏感字段索引 - User.email: 唯一索引CREATE UNIQUE INDEX idx_user_email ON User(email); - Order.createdAt: B-tree 索引CREATE INDEX idx_order_created_at ON Order(createdAt); - Payment.status: 部分索引CREATE INDEX idx_payment_status ON Payment(status) WHERE status IN (pending, failed); ### 數(shù)據(jù)完整性約束 - Order.totalAmount 必須 0且精度為 2 位小數(shù)DECIMAL(10,2) - Payment.createdAt 必須 Payment.updatedAtPrisma Schema 映射說明### Prisma 字段映射規(guī)則 - User.createdAt 對(duì)應(yīng)數(shù)據(jù)庫(kù) created_at 字段map(created_at) - User.isActive 對(duì)應(yīng)數(shù)據(jù)庫(kù) is_active 字段map(is_active) - 所有 DateTime 字段在 Prisma 中使用 db.Timestamptz確保時(shí)區(qū)安全實(shí)操心得我們?cè)驔]在## Database Schema中明確Payment.createdAt的時(shí)區(qū)要求AI 生成了db.Timestamp類型導(dǎo)致生產(chǎn)環(huán)境出現(xiàn)跨時(shí)區(qū)訂單時(shí)間錯(cuò)亂。后來我們強(qiáng)制要求所有DateTime字段的 Prisma 映射必須在此區(qū)塊中顯式聲明db.Timestamptz或db.Timestamp并在 CI 中用prisma validate檢查。4. OpenSpec Skills 集成讓 CLAUDE.md 活起來的“肌肉”4.1 Skills 的本質(zhì)可插拔的“專業(yè)能力模塊”Skills 不是插件不是腳本而是定義了“在什么條件下做什么事產(chǎn)生什么結(jié)果”的原子化能力單元。一個(gè) Skill 的生命周期完全獨(dú)立于 Claude Code 的核心引擎。你可以隨時(shí)啟用、禁用、更新、替換它而不會(huì)影響其他功能。我們團(tuán)隊(duì)目前維護(hù)著 12 個(gè)核心 Skills全部開源在內(nèi)部 GitLab 上。每個(gè) Skill 都遵循 OpenSpec 標(biāo)準(zhǔn)包含三個(gè)核心文件skill.yaml技能的“身份證”定義元信息、觸發(fā)條件、輸入輸出 schema。handler.js技能的“大腦”包含具體的業(yè)務(wù)邏輯Node.js 運(yùn)行時(shí)。README.md技能的“說明書”包含使用示例、調(diào)試指南、已知限制。以ourorg/api-doc-skill為例它的skill.yaml關(guān)鍵片段如下name: ourorg/api-doc-skill description: 根據(jù) NestJS 控制器代碼自動(dòng)生成 OpenAPI 3.0 文檔注釋 version: 1.2.0 triggers: - file_pattern: **/*.controller.ts event: file_saved input_schema: $ref: ./input.schema.json output_schema: $ref: ./output.schema.json這意味著只要你在 VS Code 中保存了一個(gè)*.controller.ts文件OpenSpec 運(yùn)行時(shí)就會(huì)自動(dòng)調(diào)用這個(gè) Skill分析你的Get()、Post()裝飾器并在方法上方插入標(biāo)準(zhǔn)的ApiOkResponse()等 Swagger 注釋。整個(gè)過程無需你手動(dòng)觸發(fā)就像 IDE 的自動(dòng)補(bǔ)全一樣自然。4.2 安裝與管理像管理 npm 包一樣管理 AI 能力Skills 的安裝完全復(fù)刻了前端開發(fā)者的熟悉流程。核心命令只有三個(gè)安裝全局 Skill適用于所有項(xiàng)目npx skills add ourorg/api-doc-skill --agent claude-code -g -y-g表示全局安裝-y表示跳過確認(rèn)。這條命令會(huì)從我們的私有 GitLab Registry 下載ourorg/api-doc-skill的 tarball解壓到~/.claude-code/skills/目錄更新~/.claude-code/config.json將該 Skill 加入globalSkills列表重啟 Claude Code Agent。安裝項(xiàng)目級(jí) Skill僅對(duì)當(dāng)前項(xiàng)目生效npx skills add ourorg/db-migration-skill --agent claude-code --project ./path/to/project -y這會(huì)在項(xiàng)目根目錄創(chuàng)建skills/文件夾并將 Skill 文件放入其中。CLAUDE.md 中的skills數(shù)組就是指向這個(gè)skills/目錄下的相對(duì)路徑。查看已安裝 Skillsnpx skills list --agent claude-code輸出會(huì)清晰顯示每個(gè) Skill 的名稱、版本、安裝位置global 或 project、狀態(tài)enabled/disabled。注意npx skills命令背后是 OpenSpec CLI 工具。它不是一個(gè)黑盒所有源碼都在openspec/cli包中。我們團(tuán)隊(duì)的 DevOps 工程師曾基于它二次開發(fā)增加了--dry-run模式用于在 CI 中預(yù)檢 Skill 安裝是否會(huì)導(dǎo)致沖突。4.3 CLAUDE.md 與 Skills 的協(xié)同上下文驅(qū)動(dòng)的智能激活CLAUDE.md 本身不執(zhí)行任何邏輯它只是“知識(shí)庫(kù)”。Skills 才是“執(zhí)行者”。兩者的協(xié)同是通過 OpenSpec 的 Context Binding 機(jī)制實(shí)現(xiàn)的。當(dāng)你在 CLAUDE.md 中寫下## Tooling Workflow ### CI/CD Pipeline - 當(dāng)前使用 GitHub Actions主工作流文件.github/workflows/deploy.yml - 構(gòu)建步驟必須運(yùn)行 pnpm run build測(cè)試步驟必須運(yùn)行 pnpm run test:e2e - 部署目標(biāo)AWS ECS集群名 prod-clusterOpenSpec 運(yùn)行時(shí)會(huì)做三件事解析提取出CI/CD Pipeline區(qū)塊的所有文本構(gòu)建成一個(gè) Context Object綁定查找所有聲明了triggers.file_pattern: .github/workflows/**的 Skills激活當(dāng)用戶編輯.github/workflows/deploy.yml時(shí)自動(dòng)加載并執(zhí)行這些 Skills。我們有一個(gè)ourorg/ci-linter-skill它會(huì)實(shí)時(shí)分析 YAML 文件檢查是否遺漏了on.push.branches的main分支jobs.deploy.steps中是否包含了aws-actions/configure-aws-credentialsv2env.AWS_REGION是否設(shè)置為us-east-1。如果發(fā)現(xiàn)違規(guī)它會(huì)直接在 VS Code 的 Problems 面板中報(bào)錯(cuò)就像 TypeScript 編譯錯(cuò)誤一樣。這比等 CI 運(yùn)行失敗后再修復(fù)效率提升了 10 倍。4.4 自定義 Skill 開發(fā)三步寫出你的第一個(gè)“超能力”開發(fā)一個(gè) Skill不需要懂 AI只需要懂 Node.js 和你的業(yè)務(wù)邏輯。以我們團(tuán)隊(duì)的ourorg/i18n-extractor-skill為例它自動(dòng)從 React 組件中提取待翻譯的字符串Step 1定義skill.yamlname: ourorg/i18n-extractor-skill description: 掃描 React 組件提取 t() 函數(shù)調(diào)用中的字符串生成 i18n/en.json version: 1.0.0 triggers: - file_pattern: **/*.tsx event: file_saved input_schema: type: object properties: filePath: type: string output_schema: type: object properties: extractedStrings: type: array items: type: stringStep 2編寫handler.jsconst fs require(fs).promises; const path require(path); module.exports async (context) { const { filePath } context.input; const content await fs.readFile(filePath, utf8); // 使用正則提取 t(hello world) 中的字符串 const regex /t\([]([^])[]\)/g; const matches [...content.matchAll(regex)]; const strings [...new Set(matches.map(m m[1]))]; // 去重 // 寫入 i18n/en.json const i18nDir path.join(path.dirname(filePath), .., i18n); await fs.mkdir(i18nDir, { recursive: true }); const enJsonPath path.join(i18nDir, en.json); const existing JSON.parse(await fs.readFile(enJsonPath, utf8) || {}); strings.forEach(str { if (!existing[str]) { existing[str] str; // 默認(rèn)值為原文 } }); await fs.writeFile(enJsonPath, JSON.stringify(existing, null, 2)); return { extractedStrings: strings }; };Step 3發(fā)布與安裝# 打包 npm pack # 發(fā)布到私有 Registry npm publish --registry https://gitlab.com/api/v4/groups/ourorg/-/project/123456789/packages/npm/ # 全局安裝 npx skills add ourorg/i18n-extractor-skill --agent claude-code -g -y實(shí)操心得我們最初以為 Skills 開發(fā)很復(fù)雜結(jié)果發(fā)現(xiàn)核心就是“接收輸入 - 處理 - 返回輸出”。最大的坑在于路徑處理——filePath是絕對(duì)路徑但 Skill 運(yùn)行時(shí)的工作目錄是~/.claude-code/所以所有fs操作必須用path.resolve()轉(zhuǎn)換。這個(gè)教訓(xùn)我們寫進(jìn)了團(tuán)隊(duì)的Skill Development Checklist里作為必檢項(xiàng)。5. 實(shí)戰(zhàn)避坑指南那些只有踩過才懂的“深水區(qū)”5.1 CLAUDE.md 的“熱加載”陷阱修改后為何 AI 沒反應(yīng)這是新手最常問的問題。答案很簡(jiǎn)單CLAUDE.md 不是實(shí)時(shí)監(jiān)聽的它只在 Claude Code Agent 啟動(dòng)時(shí)加載一次。你修改了文件必須重啟 Agent 才能生效。正確做法保存 CLAUDE.md在 VS Code 命令面板CtrlShiftP中輸入Claude Code: Restart Agent等待狀態(tài)欄顯示Agent restarted。為什么不能自動(dòng)熱加載因?yàn)?CLAUDE.md 的解析涉及大量 I/O讀取文件、解析 Markdown、構(gòu)建上下文樹頻繁重載會(huì)拖慢編輯器響應(yīng)。OpenSpec 的設(shè)計(jì)哲學(xué)是“穩(wěn)定性優(yōu)先”所以選擇了顯式重啟。提示我們團(tuán)隊(duì)在.vscode/settings.json中配置了claude-code.restartOnConfigChange: true這樣只要 CLAUDE.md 保存VS Code 就會(huì)自動(dòng)觸發(fā)重啟。但這需要 VS Code 插件版本 2.8.0。5.2 OpenSpec Skills 的“幽靈依賴”為什么 Skill 總是報(bào)錯(cuò)找不到模塊Skills 運(yùn)行在獨(dú)立的 Node.js 進(jìn)程中它有自己的node_modules。如果你在handler.js中require(prisma)而這個(gè) Skill 的package.json里沒聲明prisma為 dependency就會(huì)報(bào)Cannot find module prisma。解決方案永遠(yuǎn)遵循“零外部依賴”原則。如果必須用第三方庫(kù)把它聲明為 Skill 的dependencies并在package.json中鎖定版本更推薦的做法是用原生 Node.js API 替代。比如i18n-extractor-skill用正則而不是acorn解析 AST就是為了避免依賴。調(diào)試技巧在handler.js開頭加上console.log(NODE_ENV:, process.env.NODE_ENV); console.log(PWD:, process.cwd()); console.log(REQUIRE RESOLVE:, require.resolve(fs));這能立刻告訴你 Skill 運(yùn)行時(shí)的真實(shí)環(huán)境。5.3 Markdown 語法的“隱形殺手”為什么##區(qū)塊有時(shí)被忽略CLAUDE.md 的解析器對(duì) Markdown 語法極其嚴(yán)格。以下寫法會(huì)導(dǎo)致區(qū)塊失效錯(cuò)誤寫法 1空行缺失## API Contracts ### 請(qǐng)求頭Headers - 所有請(qǐng)求必須攜帶...? 正確寫法##和###之間必須有空行。## API Contracts ### 請(qǐng)求頭Headers - 所有請(qǐng)求必須攜帶...錯(cuò)誤寫法 2混用縮進(jìn)## Database Schema ### 用戶User與組織Organization關(guān)系? 正確寫法###必須頂格不能縮進(jìn)。## Database Schema ### 用戶User與組織Organization關(guān)系錯(cuò)誤寫法 3中文標(biāo)點(diǎn)干擾## Coding Standards // 這里是全角空格? 正確寫法所有空格必須是半角。我們?yōu)榇藢ｉT開發(fā)了一個(gè)claude-md-linterCLI 工具集成到 pre-commit hook 中自動(dòng)檢查這些格式問題。它比人工 Review 快 100 倍。5.4 Skills 的“競(jìng)態(tài)條件”兩個(gè) Skill 同時(shí)修改同一個(gè)文件怎么辦這是高并發(fā)場(chǎng)景下的真實(shí)問題。比如ourorg/api-doc-skill和ourorg/ts-type-checker-skill都監(jiān)聽*.controller.ts都試圖在文件頂部添加注釋。結(jié)果就是文件被反復(fù)覆蓋最終內(nèi)容混亂。官方解決方案OpenSpec 3.0 引入了executionOrder字段executionOrder: 10 // 數(shù)字越小優(yōu)先級(jí)越高我們給api-doc-skill設(shè)為10給ts-type-checker-skill設(shè)為20確保文檔生成永遠(yuǎn)先于類型檢查。終極保險(xiǎn)在handler.js中加文件鎖const lockFile ${filePath}.lock;