目規(guī)則實(shí)戰(zhàn)：從通用AI助手到專屬協(xié)作者的蛻變)
如果你是一名開發(fā)者最近在 VS Code 里看到同事或社區(qū)在討論一個(gè)叫 CodeBuddy 的 AI 編程助手可能會(huì)好奇它和 GitHub Copilot、Cursor 或者國內(nèi)的通義靈碼有什么區(qū)別更重要的是當(dāng)你想用它來管理一個(gè)真實(shí)項(xiàng)目時(shí)比如創(chuàng)建一個(gè)新的微服務(wù)模塊你會(huì)發(fā)現(xiàn)僅僅“問問題”是不夠的。如何讓 AI 理解你項(xiàng)目的獨(dú)特結(jié)構(gòu)、編碼規(guī)范、甚至部署流程這才是決定一個(gè) AI 助手能否從“玩具”升級為“生產(chǎn)力工具”的關(guān)鍵。CodeBuddy 給出的答案是“項(xiàng)目規(guī)則”。這聽起來像是一個(gè)簡單的配置文件但它的實(shí)際影響力遠(yuǎn)超你的想象。它本質(zhì)上是一套你與 AI 助手之間的“協(xié)作契約”定義了在你的項(xiàng)目上下文中AI 應(yīng)該如何思考、如何行動(dòng)、以及什么能做、什么不能做。沒有它AI 就像一個(gè)新來的實(shí)習(xí)生對項(xiàng)目一無所知有了它AI 就成了一個(gè)熟悉團(tuán)隊(duì)規(guī)范、了解技術(shù)棧、能高效執(zhí)行復(fù)雜任務(wù)的老手。本文將深入解析 CodeBuddy 的“項(xiàng)目規(guī)則”功能。我不會(huì)只告訴你“規(guī)則是什么”而是會(huì)帶你理解為什么你需要項(xiàng)目規(guī)則對比傳統(tǒng) AI 編碼的“盲人摸象”與規(guī)則驅(qū)動(dòng)下的“精準(zhǔn)協(xié)作”。規(guī)則的核心構(gòu)成與原理如何通過projectRules.json等文件從目錄結(jié)構(gòu)、技術(shù)棧到安全紅線全方位塑造 AI 的行為。從零到一創(chuàng)建你的第一條規(guī)則一個(gè)完整的、可運(yùn)行的實(shí)戰(zhàn)示例涵蓋前端 React 項(xiàng)目的規(guī)范。高級規(guī)則與 MCP 集成如何利用playwright mcp等技能讓 AI 直接操作瀏覽器進(jìn)行端到端測試。避坑指南與最佳實(shí)踐匯總了從網(wǎng)絡(luò)討論中提煉的常見問題如missing jcef runtime錯(cuò)誤、API Key 配置、以及與 WorkBuddy 的對比選擇。無論你是想提升現(xiàn)有項(xiàng)目的 AI 協(xié)作效率還是正準(zhǔn)備在新項(xiàng)目中引入 CodeBuddy理解并善用“項(xiàng)目規(guī)則”都將是你解鎖其全部潛力的第一步。1. 項(xiàng)目規(guī)則從“通用聊天”到“專屬協(xié)作者”的質(zhì)變在深入技術(shù)細(xì)節(jié)之前我們必須先回答一個(gè)根本問題為什么 CodeBuddy 要設(shè)計(jì)“項(xiàng)目規(guī)則”這個(gè)看起來有點(diǎn)復(fù)雜的概念直接讓 AI 讀代碼不就行了嗎想象兩個(gè)場景場景 A無規(guī)則你打開一個(gè)陌生的 Java Spring Boot 項(xiàng)目對 CodeBuddy 說“幫我創(chuàng)建一個(gè)用戶登錄的 API 接口。” AI 可能會(huì)生成代碼但它不知道這個(gè)項(xiàng)目用的是 MyBatis-Plus 還是 JPA不知道統(tǒng)一響應(yīng)體格式是Result還是CommonResponse不知道異常處理全局用的是ControllerAdvice還是 Filter。結(jié)果就是生成的代碼風(fēng)格突兀甚至無法運(yùn)行你需要花費(fèi)大量時(shí)間修改和調(diào)整。場景 B有規(guī)則同樣的項(xiàng)目但你已經(jīng)配置了項(xiàng)目規(guī)則。規(guī)則中明確了技術(shù)棧Spring Boot 3.x MyBatis-Plus JWT、項(xiàng)目分層結(jié)構(gòu)controller/service/mapper/entity、代碼規(guī)范使用 LombokAPI 返回ResultT。此時(shí)你再發(fā)出同樣的指令A(yù)I 生成的代碼會(huì)直接放在正確的包路徑下使用正確的依賴和工具類風(fēng)格與現(xiàn)有代碼庫完全一致幾乎可以即插即用。這個(gè)差異的核心在于“上下文邊界”。沒有規(guī)則AI 的上下文僅限于當(dāng)前打開的文件和它自身的通用知識(shí)這導(dǎo)致了“上下文幻覺”——它以為它懂了但其實(shí)不懂你的項(xiàng)目特異性。項(xiàng)目規(guī)則的作用就是主動(dòng)、結(jié)構(gòu)化地將項(xiàng)目特有的知識(shí)注入到 AI 的上下文中縮小其認(rèn)知差距。具體來說一個(gè)完善的項(xiàng)目規(guī)則能解決以下痛點(diǎn)目錄結(jié)構(gòu)導(dǎo)航告訴 AIsrc/main/java下是業(yè)務(wù)代碼resources下是配置文件測試代碼在哪里。避免 AI 把文件創(chuàng)建到錯(cuò)誤的位置。技術(shù)棧約束明確項(xiàng)目使用的框架、庫及其版本。防止 AI 推薦或使用未引入的依賴。代碼規(guī)范與風(fēng)格定義命名規(guī)范如 RESTful 接口路徑、代碼格式如使用特定注解、甚至禁止的模式如避免使用System.out.println。安全與合規(guī)紅線設(shè)定絕對禁止的操作例如“不允許直接編寫 SQL 字符串拼接必須使用參數(shù)化查詢或 ORM 方法”。工作流集成通過 MCPModel Context Protocol集成外部工具如讓 AI 調(diào)用playwright進(jìn)行自動(dòng)化測試或連接數(shù)據(jù)庫 Schema 服務(wù)來生成準(zhǔn)確的模型代碼。所以創(chuàng)建項(xiàng)目規(guī)則不是一個(gè)可選的“高級功能”而是將 CodeBuddy 融入你核心開發(fā)流程的必要奠基工作。它讓 AI 從“一個(gè)偶爾能給出好建議的旁觀者”轉(zhuǎn)變?yōu)槟銏F(tuán)隊(duì)中一個(gè)理解并遵守開發(fā)規(guī)范的正式成員。2. 核心概念解析規(guī)則文件、技能與 MCP在開始配置之前我們需要清晰理解 CodeBuddy 規(guī)則體系的幾個(gè)核心概念這能幫助你在后續(xù)遇到問題時(shí)知道該去哪里尋找答案。2.1 項(xiàng)目規(guī)則文件 (projectRules.json)這是項(xiàng)目規(guī)則的核心載體是一個(gè) JSON 格式的配置文件。通常位于項(xiàng)目的根目錄或.codebuddy目錄下。它定義了針對本項(xiàng)目的靜態(tài)規(guī)則。一個(gè)規(guī)則文件通常包含以下維度項(xiàng)目概述項(xiàng)目名稱、描述、主要技術(shù)棧。目錄結(jié)構(gòu)說明關(guān)鍵目錄的用途例如哪些是源碼目錄、測試目錄、資源目錄、構(gòu)建輸出目錄。代碼規(guī)范語言特定的約定如 Java 的包命名、Python 的導(dǎo)入順序、JavaScript 的模塊化規(guī)范。依賴管理使用的包管理器Maven, npm, pip以及核心依賴的版本傾向。任務(wù)模板預(yù)定義一些常見開發(fā)任務(wù)的步驟描述供 AI 參考執(zhí)行。禁止事項(xiàng)明確列出不允許 AI 執(zhí)行的操作如直接操作生產(chǎn)數(shù)據(jù)庫、刪除特定文件等。2.2 技能技能是 CodeBuddy 可以執(zhí)行的原子操作。你可以把它理解為 AI 的“工具包”。一些技能是內(nèi)置的如“文件讀寫”、“終端命令執(zhí)行”、“代碼分析”。而更強(qiáng)大的技能則來自MCP 集成。2.3 MCP 與外部工具集成MCP 是 CodeBuddy 能力擴(kuò)展的關(guān)鍵。它允許 CodeBuddy 連接外部服務(wù)器從而獲得新的“技能”。網(wǎng)絡(luò)熱詞中提到的codebuddy playwright mcp就是一個(gè)典型例子。playwright mcp集成后你可以直接對 CodeBuddy 說“為剛才創(chuàng)建的登錄頁面寫一個(gè) Playwright 測試并運(yùn)行它。” CodeBuddy 不僅能生成測試代碼還能通過 MCP 調(diào)用本地的 Playwright 環(huán)境來執(zhí)行測試并將結(jié)果反饋給你。這實(shí)現(xiàn)了從代碼生成到驗(yàn)證的閉環(huán)。其他 MCP理論上任何可以通過 MCP 協(xié)議暴露的工具都可以集成如數(shù)據(jù)庫客戶端、云服務(wù) CLI、內(nèi)部部署系統(tǒng)等。2.4 CodeBuddy vs. WorkBuddy網(wǎng)絡(luò)熱詞中頻繁出現(xiàn)兩者的對比。簡單區(qū)分CodeBuddy定位是開發(fā)者個(gè)人的 AI 結(jié)對編程助手深度集成在 VS Code 等 IDE 中核心場景是寫代碼、調(diào)試、理解項(xiàng)目。其“項(xiàng)目規(guī)則”聚焦于代碼本身的規(guī)范和上下文。WorkBuddy定位更偏向團(tuán)隊(duì)任務(wù)管理與自動(dòng)化協(xié)作可能集成在 Slack、Teams 等辦公工具中核心場景是管理工單、跟蹤進(jìn)度、協(xié)調(diào)資源。其“規(guī)則”可能更側(cè)重于工作流程和權(quán)限。對于開發(fā)者而言在 VS Code 中管理項(xiàng)目代碼CodeBuddy 是更直接和強(qiáng)大的選擇。本文討論的“項(xiàng)目規(guī)則”也特指 CodeBuddy 的范疇。3. 環(huán)境準(zhǔn)備與 CodeBuddy 基礎(chǔ)配置在創(chuàng)建規(guī)則之前你需要確保 CodeBuddy 已經(jīng)在你的開發(fā)環(huán)境中正確運(yùn)行。3.1 安裝 CodeBuddyCodeBuddy 主要作為 VS Code 擴(kuò)展提供。打開 VS Code。進(jìn)入擴(kuò)展市場 (CtrlShiftX)。搜索CodeBuddy。找到官方擴(kuò)展并點(diǎn)擊安裝。3.2 配置 API Key網(wǎng)絡(luò)熱詞中提到了vscode中如何通過apikey使用codebuddy。CodeBuddy 通常需要一個(gè)大模型 API Key 來驅(qū)動(dòng)如 OpenAI GPT, Anthropic Claude 等。安裝擴(kuò)展后VS Code 側(cè)邊欄會(huì)出現(xiàn) CodeBuddy 圖標(biāo)。點(diǎn)擊圖標(biāo)通常會(huì)引導(dǎo)你進(jìn)行初始設(shè)置。在設(shè)置中找到API Configuration或類似選項(xiàng)。填入你從相應(yīng) AI 服務(wù)商處獲得的 API Key。重要確保你的網(wǎng)絡(luò)環(huán)境可以正常訪問該 API 服務(wù)。關(guān)于網(wǎng)絡(luò)連通性問題請遵守當(dāng)?shù)胤煞ㄒ?guī)和使用條款使用合規(guī)的互聯(lián)網(wǎng)服務(wù)。3.3 驗(yàn)證安裝與排查常見啟動(dòng)錯(cuò)誤安裝后嘗試在 VS Code 中喚出 CodeBuddy通常通過命令面板CtrlShiftP輸入CodeBuddy。如果遇到問題請檢查以下網(wǎng)絡(luò)高頻錯(cuò)誤問題missing jcef runtime codebuddy relies on jcef (java chromium embedded framework)這是一個(gè)常見的啟動(dòng)錯(cuò)誤?？赡茉駽odeBuddy 的某些 UI 組件依賴于 JCEF但你的 Java 環(huán)境或 VS Code 環(huán)境缺少必要的運(yùn)行時(shí)。排查與解決更新 VS Code 和 CodeBuddy 擴(kuò)展確保使用最新版本。檢查 Java 環(huán)境確保系統(tǒng)已安裝合適版本的 JDK如 JDK 11, 17。在終端輸入java -version驗(yàn)證。查閱官方文檔前往 CodeBuddy 的官方 GitHub 或文檔站查看針對此錯(cuò)誤的特定解決方案。有時(shí)可能需要手動(dòng)下載某個(gè)組件。簡化啟動(dòng)嘗試在 CodeBuddy 設(shè)置中禁用一些高級的圖形化功能看是否能繞過此錯(cuò)誤。完成以上基礎(chǔ)配置并成功啟動(dòng) CodeBuddy 后我們就可以開始為核心項(xiàng)目創(chuàng)建規(guī)則了。4. 實(shí)戰(zhàn)為 React 項(xiàng)目創(chuàng)建你的第一份projectRules.json讓我們以一個(gè)典型的現(xiàn)代前端項(xiàng)目為例創(chuàng)建一個(gè)完整的項(xiàng)目規(guī)則。假設(shè)我們有一個(gè)使用 Vite React TypeScript Tailwind CSS 的項(xiàng)目項(xiàng)目結(jié)構(gòu)如下my-react-app/ ├── .codebuddy/ # 我們準(zhǔn)備把規(guī)則文件放在這里 ├── src/ │ ├── components/ │ ├── pages/ │ ├── hooks/ │ ├── utils/ │ ├── types/ │ ├── App.tsx │ └── main.tsx ├── public/ ├── package.json ├── tsconfig.json ├── tailwind.config.js └── vite.config.ts4.1 創(chuàng)建規(guī)則文件在項(xiàng)目根目錄下創(chuàng)建.codebuddy文件夾如果不存在然后在該文件夾內(nèi)創(chuàng)建projectRules.json文件。// 文件路徑.codebuddy/projectRules.json { version: 1.0, project: { name: My React Dashboard, description: 一個(gè)使用 Vite React TypeScript Tailwind CSS 構(gòu)建的管理后臺(tái)前端項(xiàng)目。, techStack: [React 18, TypeScript 5.x, Vite, Tailwind CSS, React Router DOM] }, directoryStructure: { source: src/, description: 所有源代碼文件均位于 src 目錄下。, keyDirectories: [ { path: src/components, purpose: 存放可復(fù)用的 UI 組件。組件應(yīng)使用 PascalCase 命名如 Button.tsx。每個(gè)組件應(yīng)有自己的目錄包含索引文件、組件文件和樣式文件如果使用 CSS Modules。 }, { path: src/pages, purpose: 存放頁面級組件。與路由一一對應(yīng)。 }, { path: src/hooks, purpose: 存放自定義 React Hooks。應(yīng)以 use 開頭如 useLocalStorage.ts。 }, { path: src/utils, purpose: 存放工具函數(shù)。應(yīng)是純函數(shù)且做好單元測試。 }, { path: src/types, purpose: 存放 TypeScript 類型定義和接口。 } ], ignorePatterns: [node_modules, dist, build, .git] }, codeConventions: { language: typescript, rules: [ 使用函數(shù)式組件和 React Hooks除非有特殊理由否則避免使用類組件。, 組件 Props 必須使用 TypeScript 接口或類型進(jìn)行嚴(yán)格定義。, 優(yōu)先使用命名導(dǎo)出Named Export而非默認(rèn)導(dǎo)出Default Export。, 使用 ES6 語法如箭頭函數(shù)、解構(gòu)賦值、可選鏈?.。, 樣式方案主要使用 Tailwind CSS 工具類。對于復(fù)雜組件可搭配 CSS Modules文件命名為 *.module.css。禁止內(nèi)聯(lián) style 對象和全局 CSS 污染。, 狀態(tài)管理簡單的組件狀態(tài)使用 useState?？缃M件狀態(tài)使用 Context API。復(fù)雜場景預(yù)留 Redux Toolkit 集成可能但當(dāng)前項(xiàng)目未安裝。, HTTP 客戶端使用 axios 進(jìn)行 API 調(diào)用。所有請求應(yīng)封裝在 src/services/ 目錄下的模塊中。, 路由使用 React Router DOM。路由定義應(yīng)集中管理。 ] }, dependencyManagement: { packageManager: npm, lockFile: package-lock.json, keyDependencies: { react: ^18.2.0, react-dom: ^18.2.0, typescript: ~5.2.0, types/react: ^18.2.0, axios: ^1.6.0, react-router-dom: ^6.20.0 } }, taskTemplates: [ { name: 創(chuàng)建新組件, steps: [ 1. 在 src/components 下創(chuàng)建以組件名命名的文件夾PascalCase。, 2. 在該文件夾內(nèi)創(chuàng)建 index.ts 文件用于導(dǎo)出組件。, 3. 創(chuàng)建 ComponentName.tsx 文件作為主組件。, 4. 如果需要樣式創(chuàng)建 ComponentName.module.css 文件。, 5. 在組件文件中定義 Props 接口實(shí)現(xiàn)函數(shù)式組件使用 Tailwind 類名。, 6. 在 index.ts 中導(dǎo)出組件。 ] }, { name: 添加新頁面及路由, steps: [ 1. 在 src/pages 下創(chuàng)建頁面組件文件如 UserProfile.tsx。, 2. 在路由配置文件如 src/router/index.tsx中導(dǎo)入該頁面組件并添加到路由數(shù)組中。, 3. 確保路由路徑符合 RESTful 約定。 ] } ], restrictions: [ 禁止直接操作 DOM如 document.getElementById必須使用 React 的 ref 或狀態(tài)驅(qū)動(dòng)。, 禁止在組件內(nèi)部或服務(wù)模塊中硬編碼 API 基礎(chǔ) URL。應(yīng)從環(huán)境變量 VITE_API_BASE_URL 讀取。, 禁止提交包含 console.log 調(diào)試語句的代碼請使用調(diào)試器或移除。, 所有對外部 API 的調(diào)用必須進(jìn)行錯(cuò)誤處理try-catch 或 .catch。 ] }4.2 規(guī)則文件詳解project為 AI 提供項(xiàng)目背景幫助它理解項(xiàng)目的宏觀目標(biāo)。directoryStructure這是最立竿見影的部分。明確目錄用途后當(dāng)你讓 AI “創(chuàng)建一個(gè)用戶頭像組件”它會(huì)毫不猶豫地放到src/components/Avatar下而不是別處。codeConventions定義了代碼的“法律”。它強(qiáng)制 AI 生成的代碼符合團(tuán)隊(duì)規(guī)范極大減少代碼審查時(shí)的風(fēng)格沖突。dependencyManagement防止 AI 建議安裝項(xiàng)目未聲明或版本不兼容的包。taskTemplates將常見工作流固化。AI 在執(zhí)行“創(chuàng)建組件”任務(wù)時(shí)會(huì)遵循這些步驟確保產(chǎn)出結(jié)構(gòu)一致。restrictions設(shè)定安全與質(zhì)量紅線。這是防止 AI 引入低級錯(cuò)誤或安全漏洞的關(guān)鍵。保存這個(gè)文件后CodeBuddy 在分析你的項(xiàng)目時(shí)就會(huì)加載這些規(guī)則。你可以立即嘗試在 VS Code 中打開項(xiàng)目對 CodeBuddy 說“在src/components下創(chuàng)建一個(gè)Button組件包含 primary 和 secondary 兩種變體?！?觀察生成的代碼你會(huì)發(fā)現(xiàn)它更有可能遵循你定義的 TypeScript 接口、Tailwind 類名規(guī)范和目錄結(jié)構(gòu)。5. 進(jìn)階集成 MCP 技能以 Playwright 為例現(xiàn)在讓我們?yōu)轫?xiàng)目添加自動(dòng)化測試能力。我們將集成playwright mcp讓 CodeBuddy 不僅能寫測試還能運(yùn)行測試。5.1 安裝 Playwright MCP 服務(wù)器首先你需要確保 Playwright MCP 服務(wù)器可用。這通常是一個(gè)獨(dú)立的進(jìn)程或服務(wù)。具體安裝方式需參考codebuddy-playwright-mcp的官方文檔。假設(shè)你已經(jīng)通過 npm 全局安裝或克隆了相關(guān)倉庫。# 假設(shè)安裝方式是通過 npm請以實(shí)際 MCP 包名為準(zhǔn) npm install -g codebuddy/playwright-mcp-server5.2 配置 CodeBuddy 連接 MCP接下來需要在 CodeBuddy 的配置中告知它這個(gè) MCP 服務(wù)器的位置。配置可能位于 VS Code 的用戶設(shè)置 (settings.json) 或 CodeBuddy 的專屬配置文件中。// 文件路徑.vscode/settings.json 或 CodeBuddy 配置界面 { codebuddy.mcpServers: { playwright: { command: npx, args: [codebuddy/playwright-mcp-server], env: { // 可選的環(huán)境變量 } } } }5.3 在項(xiàng)目規(guī)則中聲明技能然后在你的projectRules.json中可以添加一個(gè)skills或mcpIntegrations部分聲明本項(xiàng)目可用的高級技能。// 在 .codebuddy/projectRules.json 中添加 { // ... 之前的配置保持不變 ... mcpIntegrations: [ { name: playwright, description: 用于端到端E2E測試?？梢跃帉?、運(yùn)行和調(diào)試 Playwright 測試腳本。, capabilities: [ generate_e2e_test, run_test, inspect_page ] } ], taskTemplates: [ // ... 原有的任務(wù)模板 ... { name: 為頁面生成并運(yùn)行 E2E 測試, steps: [ 1. 使用 Playwright MCP 技能分析目標(biāo)頁面如 /login的 DOM 結(jié)構(gòu)。, 2. 在 tests/e2e/ 目錄下生成一個(gè) Playwright 測試文件如 login.spec.ts。, 3. 測試應(yīng)包含頁面導(dǎo)航、元素定位、交互輸入、點(diǎn)擊和斷言。, 4. 使用 Playwright MCP 技能運(yùn)行生成的測試并報(bào)告結(jié)果。 ], requiredSkill: playwright } ] }5.4 使用技能配置完成后你可以向 CodeBuddy 發(fā)出更強(qiáng)大的指令“為我們的登錄頁面/login生成一個(gè) Playwright E2E 測試檢查用戶輸入錯(cuò)誤密碼時(shí)的提示信息并運(yùn)行這個(gè)測試?！盋odeBuddy 會(huì)理解你的項(xiàng)目規(guī)則知道測試文件應(yīng)放在tests/e2e/。調(diào)用 Playwright MCP 技能分析登錄頁面的實(shí)際元素。生成符合項(xiàng)目代碼規(guī)范的測試腳本。再次調(diào)用 MCP 技能在后臺(tái)啟動(dòng)瀏覽器運(yùn)行測試并將成功或失敗的結(jié)果反饋給你。這就實(shí)現(xiàn)了從需求到驗(yàn)證的自動(dòng)化閉環(huán)極大地提升了前端測試的效率和可靠性。6. 運(yùn)行驗(yàn)證與效果評估如何驗(yàn)證你的項(xiàng)目規(guī)則是否生效可以通過幾個(gè)簡單的測試測試 1目錄結(jié)構(gòu)遵從性指令“創(chuàng)建一個(gè)顯示用戶列表的組件叫UserTable。”預(yù)期結(jié)果在src/components/UserTable/目錄下生成index.ts和UserTable.tsx文件。驗(yàn)證檢查生成的文件路徑是否正確。測試 2代碼規(guī)范遵從性指令“在UserTable組件里添加一個(gè)從/api/users獲取數(shù)據(jù)的函數(shù)?！鳖A(yù)期結(jié)果生成的函數(shù)使用axios。API URL 不是硬編碼而是使用了VITE_API_BASE_URL環(huán)境變量根據(jù)規(guī)則。函數(shù)被放在一個(gè)useEffect或自定義 Hook 中并有錯(cuò)誤處理。驗(yàn)證檢查生成的代碼片段是否符合restrictions和codeConventions中的規(guī)則。測試 3任務(wù)模板觸發(fā)指令“按照‘創(chuàng)建新組件’的流程做一個(gè)Modal對話框組件。”預(yù)期結(jié)果AI 的回復(fù)或生成的文件結(jié)構(gòu)會(huì)清晰地反映出任務(wù)模板中定義的步驟。驗(yàn)證觀察 AI 的思考過程或輸出是否結(jié)構(gòu)化。如果測試結(jié)果不符合預(yù)期請進(jìn)入下一節(jié)的排查環(huán)節(jié)。7. 常見問題與排查思路以下是基于網(wǎng)絡(luò)討論和實(shí)際使用中可能遇到的問題匯總問題現(xiàn)象可能原因排查方式解決方案CodeBuddy 完全忽略項(xiàng)目規(guī)則行為像沒配置一樣。1. 規(guī)則文件路徑錯(cuò)誤或文件名不對。2. 規(guī)則文件 JSON 格式有語法錯(cuò)誤。3. CodeBuddy 未正確加載項(xiàng)目上下文。1. 檢查.codebuddy/projectRules.json文件是否存在且路徑正確。2. 使用 JSON 驗(yàn)證工具檢查文件語法。3. 在 VS Code 中確保打開的是項(xiàng)目根目錄并重啟 CodeBuddy 面板。1. 確保文件在正確位置。2. 修正 JSON 語法錯(cuò)誤。3. 重啟 VS Code 或重新加載 CodeBuddy 擴(kuò)展。AI 生成的代碼風(fēng)格與規(guī)則不符如用了類組件。1. 規(guī)則描述不夠具體或存在歧義。2. AI 的底層模型未能完全理解規(guī)則。3. 規(guī)則與其他指令沖突。1. 檢查codeConventions.rules是否表述清晰。例如明確寫“禁止使用類組件”。2. 在指令中更明確地強(qiáng)調(diào)規(guī)則如“請嚴(yán)格遵守項(xiàng)目規(guī)則中關(guān)于使用函數(shù)式組件的規(guī)定”。1. 細(xì)化規(guī)則描述使用肯定/否定句明確要求。2. 結(jié)合指令明確約束。規(guī)則是一個(gè)強(qiáng)提示并非絕對強(qiáng)制。集成 MCP如 Playwright失敗AI 說找不到該技能。1. MCP 服務(wù)器未啟動(dòng)或命令配置錯(cuò)誤。2. CodeBuddy 配置中 MCP 服務(wù)器路徑不正確。3. 項(xiàng)目規(guī)則中mcpIntegrations聲明有誤。1. 手動(dòng)在終端嘗試啟動(dòng) MCP 服務(wù)器命令看是否報(bào)錯(cuò)。2. 檢查settings.json中codebuddy.mcpServers的配置。3. 確認(rèn)項(xiàng)目規(guī)則中技能名稱與配置的服務(wù)器名稱匹配。1. 根據(jù) MCP 服務(wù)器文檔確保其正確安裝和運(yùn)行。2. 修正 VS Code 或 CodeBuddy 的配置。3. 確保規(guī)則文件中的技能聲明準(zhǔn)確。遇到missing jcef runtime錯(cuò)誤無法啟動(dòng) CodeBuddy UI。CodeBuddy 的圖形界面依賴 JCEF 組件缺失或版本不兼容。1. 查看完整錯(cuò)誤日志。2. 檢查 VS Code 版本和 CodeBuddy 擴(kuò)展版本。1.首選更新 VS Code 和 CodeBuddy 擴(kuò)展至最新版。2. 根據(jù)官方 Issue 或文檔可能需要安裝特定版本的 JDK 或手動(dòng)下載 JCEF 庫。3.臨時(shí)方案在設(shè)置中嘗試禁用 CodeBuddy 的某些可視化功能。AI 對項(xiàng)目目錄的理解仍然有偏差。directoryStructure描述不夠詳細(xì)或者項(xiàng)目存在非常規(guī)結(jié)構(gòu)。讓 AI 描述它當(dāng)前理解的項(xiàng)目結(jié)構(gòu)。在規(guī)則文件中為每個(gè)重要目錄添加更詳細(xì)的purpose描述。對于復(fù)雜項(xiàng)目可以考慮提供一個(gè)簡化的架構(gòu)圖說明。如何領(lǐng)取或使用codebuddy積分“積分”可能指某些云服務(wù)或商業(yè)版的額度/點(diǎn)數(shù)系統(tǒng)。查閱 CodeBuddy 的官方定價(jià)、訂閱或活動(dòng)頁面。這通常與本地項(xiàng)目規(guī)則配置無關(guān)。請參考 CodeBuddy 官方網(wǎng)站或訂閱郵件獲取相關(guān)信息。8. 最佳實(shí)踐與工程建議為了讓項(xiàng)目規(guī)則發(fā)揮最大效用并使其易于維護(hù)請遵循以下建議版本化規(guī)則文件將.codebuddy/projectRules.json納入版本控制系統(tǒng)如 Git。這樣團(tuán)隊(duì)所有成員都使用同一套規(guī)則保證了協(xié)作的一致性。漸進(jìn)式完善不要試圖一次性寫出完美的規(guī)則。從最痛的痛點(diǎn)開始比如目錄結(jié)構(gòu)然后隨著使用逐步添加代碼規(guī)范、任務(wù)模板和限制項(xiàng)。規(guī)則描述具體化避免使用“代碼要整潔”這類模糊描述。使用具體、可執(zhí)行的語句如“函數(shù)長度不應(yīng)超過50行”、“React 組件必須使用React.memo進(jìn)行性能優(yōu)化如果合適”。區(qū)分強(qiáng)制與推薦在restrictions中放置必須遵守的條款如安全紅線。在codeConventions中放置強(qiáng)烈推薦的規(guī)范?？梢栽谧⑨屩姓f明原因。為多模塊項(xiàng)目配置對于大型 Monorepo 或微服務(wù)項(xiàng)目可以在根目錄設(shè)置通用規(guī)則然后在子模塊的.codebuddy目錄下配置更具體的規(guī)則。CodeBuddy 通常會(huì)合并或就近應(yīng)用規(guī)則。定期復(fù)審規(guī)則技術(shù)棧和團(tuán)隊(duì)規(guī)范會(huì)演進(jìn)。每個(gè)季度或半年團(tuán)隊(duì)?wèi)?yīng)一起復(fù)審項(xiàng)目規(guī)則更新過時(shí)的約定添加新的最佳實(shí)踐。結(jié)合代碼檢查工具項(xiàng)目規(guī)則是給 AI 看的“軟約束”。還應(yīng)配置 ESLint、Prettier、SonarQube 等工具作為“硬約束”在 CI/CD 流水線中自動(dòng)執(zhí)行形成雙重保障。安全第一restrictions部分是設(shè)置安全邊界的關(guān)鍵。務(wù)必包含禁止硬編碼密碼/密鑰、禁止危險(xiǎn)的數(shù)據(jù)庫操作、禁止引入已知高危依賴等條款。通過創(chuàng)建和維護(hù)一個(gè)精良的projectRules.json文件你不僅僅是在配置一個(gè)工具更是在為你的項(xiàng)目定義一份活的、可執(zhí)行的開發(fā)憲法。它讓 CodeBuddy 這個(gè)強(qiáng)大的 AI 助手真正融入了你的技術(shù)棧和團(tuán)隊(duì)文化從“能寫代碼”進(jìn)化到“能寫好這個(gè)項(xiàng)目的代碼”。最終衡量項(xiàng)目規(guī)則成功與否的標(biāo)準(zhǔn)很簡單當(dāng)你給 AI 一個(gè)任務(wù)后不再需要反復(fù)糾正它的基礎(chǔ)錯(cuò)誤而是可以專注于討論更復(fù)雜的邏輯和架構(gòu)設(shè)計(jì)。這時(shí)你就已經(jīng)跨越了人機(jī)協(xié)作的第一個(gè)重要門檻。 CodeBuddy項(xiàng)目規(guī)則實(shí)戰(zhàn)：從通用AI助手到專屬協(xié)作者的蛻變
如果你是一名開發(fā)者最近在 VS Code 里看到同事或社區(qū)在討論一個(gè)叫 CodeBuddy 的 AI 編程助手可能會(huì)好奇它和 GitHub Copilot、Cursor 或者國內(nèi)的通義靈碼有什么區(qū)別更重要的是當(dāng)你想用它來管理一個(gè)真實(shí)項(xiàng)目時(shí)比如創(chuàng)建一個(gè)新的微服務(wù)模塊你會(huì)發(fā)現(xiàn)僅僅“問問題”是不夠的。如何讓 AI 理解你項(xiàng)目的獨(dú)特結(jié)構(gòu)、編碼規(guī)范、甚至部署流程這才是決定一個(gè) AI 助手能否從“玩具”升級為“生產(chǎn)力工具”的關(guān)鍵。CodeBuddy 給出的答案是“項(xiàng)目規(guī)則”。這聽起來像是一個(gè)簡單的配置文件但它的實(shí)際影響力遠(yuǎn)超你的想象。它本質(zhì)上是一套你與 AI 助手之間的“協(xié)作契約”定義了在你的項(xiàng)目上下文中AI 應(yīng)該如何思考、如何行動(dòng)、以及什么能做、什么不能做。沒有它AI 就像一個(gè)新來的實(shí)習(xí)生對項(xiàng)目一無所知有了它AI 就成了一個(gè)熟悉團(tuán)隊(duì)規(guī)范、了解技術(shù)棧、能高效執(zhí)行復(fù)雜任務(wù)的老手。本文將深入解析 CodeBuddy 的“項(xiàng)目規(guī)則”功能。我不會(huì)只告訴你“規(guī)則是什么”而是會(huì)帶你理解為什么你需要項(xiàng)目規(guī)則對比傳統(tǒng) AI 編碼的“盲人摸象”與規(guī)則驅(qū)動(dòng)下的“精準(zhǔn)協(xié)作”。規(guī)則的核心構(gòu)成與原理如何通過projectRules.json等文件從目錄結(jié)構(gòu)、技術(shù)棧到安全紅線全方位塑造 AI 的行為。從零到一創(chuàng)建你的第一條規(guī)則一個(gè)完整的、可運(yùn)行的實(shí)戰(zhàn)示例涵蓋前端 React 項(xiàng)目的規(guī)范。高級規(guī)則與 MCP 集成如何利用playwright mcp等技能讓 AI 直接操作瀏覽器進(jìn)行端到端測試。避坑指南與最佳實(shí)踐匯總了從網(wǎng)絡(luò)討論中提煉的常見問題如missing jcef runtime錯(cuò)誤、API Key 配置、以及與 WorkBuddy 的對比選擇。無論你是想提升現(xiàn)有項(xiàng)目的 AI 協(xié)作效率還是正準(zhǔn)備在新項(xiàng)目中引入 CodeBuddy理解并善用“項(xiàng)目規(guī)則”都將是你解鎖其全部潛力的第一步。1. 項(xiàng)目規(guī)則從“通用聊天”到“專屬協(xié)作者”的質(zhì)變在深入技術(shù)細(xì)節(jié)之前我們必須先回答一個(gè)根本問題為什么 CodeBuddy 要設(shè)計(jì)“項(xiàng)目規(guī)則”這個(gè)看起來有點(diǎn)復(fù)雜的概念直接讓 AI 讀代碼不就行了嗎想象兩個(gè)場景場景 A無規(guī)則你打開一個(gè)陌生的 Java Spring Boot 項(xiàng)目對 CodeBuddy 說“幫我創(chuàng)建一個(gè)用戶登錄的 API 接口。” AI 可能會(huì)生成代碼但它不知道這個(gè)項(xiàng)目用的是 MyBatis-Plus 還是 JPA不知道統(tǒng)一響應(yīng)體格式是Result還是CommonResponse不知道異常處理全局用的是ControllerAdvice還是 Filter。結(jié)果就是生成的代碼風(fēng)格突兀甚至無法運(yùn)行你需要花費(fèi)大量時(shí)間修改和調(diào)整。場景 B有規(guī)則同樣的項(xiàng)目但你已經(jīng)配置了項(xiàng)目規(guī)則。規(guī)則中明確了技術(shù)棧Spring Boot 3.x MyBatis-Plus JWT、項(xiàng)目分層結(jié)構(gòu)controller/service/mapper/entity、代碼規(guī)范使用 LombokAPI 返回ResultT。此時(shí)你再發(fā)出同樣的指令A(yù)I 生成的代碼會(huì)直接放在正確的包路徑下使用正確的依賴和工具類風(fēng)格與現(xiàn)有代碼庫完全一致幾乎可以即插即用。這個(gè)差異的核心在于“上下文邊界”。沒有規(guī)則AI 的上下文僅限于當(dāng)前打開的文件和它自身的通用知識(shí)這導(dǎo)致了“上下文幻覺”——它以為它懂了但其實(shí)不懂你的項(xiàng)目特異性。項(xiàng)目規(guī)則的作用就是主動(dòng)、結(jié)構(gòu)化地將項(xiàng)目特有的知識(shí)注入到 AI 的上下文中縮小其認(rèn)知差距。具體來說一個(gè)完善的項(xiàng)目規(guī)則能解決以下痛點(diǎn)目錄結(jié)構(gòu)導(dǎo)航告訴 AIsrc/main/java下是業(yè)務(wù)代碼resources下是配置文件測試代碼在哪里。避免 AI 把文件創(chuàng)建到錯(cuò)誤的位置。技術(shù)棧約束明確項(xiàng)目使用的框架、庫及其版本。防止 AI 推薦或使用未引入的依賴。代碼規(guī)范與風(fēng)格定義命名規(guī)范如 RESTful 接口路徑、代碼格式如使用特定注解、甚至禁止的模式如避免使用System.out.println。安全與合規(guī)紅線設(shè)定絕對禁止的操作例如“不允許直接編寫 SQL 字符串拼接必須使用參數(shù)化查詢或 ORM 方法”。工作流集成通過 MCPModel Context Protocol集成外部工具如讓 AI 調(diào)用playwright進(jìn)行自動(dòng)化測試或連接數(shù)據(jù)庫 Schema 服務(wù)來生成準(zhǔn)確的模型代碼。所以創(chuàng)建項(xiàng)目規(guī)則不是一個(gè)可選的“高級功能”而是將 CodeBuddy 融入你核心開發(fā)流程的必要奠基工作。它讓 AI 從“一個(gè)偶爾能給出好建議的旁觀者”轉(zhuǎn)變?yōu)槟銏F(tuán)隊(duì)中一個(gè)理解并遵守開發(fā)規(guī)范的正式成員。2. 核心概念解析規(guī)則文件、技能與 MCP在開始配置之前我們需要清晰理解 CodeBuddy 規(guī)則體系的幾個(gè)核心概念這能幫助你在后續(xù)遇到問題時(shí)知道該去哪里尋找答案。2.1 項(xiàng)目規(guī)則文件 (projectRules.json)這是項(xiàng)目規(guī)則的核心載體是一個(gè) JSON 格式的配置文件。通常位于項(xiàng)目的根目錄或.codebuddy目錄下。它定義了針對本項(xiàng)目的靜態(tài)規(guī)則。一個(gè)規(guī)則文件通常包含以下維度項(xiàng)目概述項(xiàng)目名稱、描述、主要技術(shù)棧。目錄結(jié)構(gòu)說明關(guān)鍵目錄的用途例如哪些是源碼目錄、測試目錄、資源目錄、構(gòu)建輸出目錄。代碼規(guī)范語言特定的約定如 Java 的包命名、Python 的導(dǎo)入順序、JavaScript 的模塊化規(guī)范。依賴管理使用的包管理器Maven, npm, pip以及核心依賴的版本傾向。任務(wù)模板預(yù)定義一些常見開發(fā)任務(wù)的步驟描述供 AI 參考執(zhí)行。禁止事項(xiàng)明確列出不允許 AI 執(zhí)行的操作如直接操作生產(chǎn)數(shù)據(jù)庫、刪除特定文件等。2.2 技能技能是 CodeBuddy 可以執(zhí)行的原子操作。你可以把它理解為 AI 的“工具包”。一些技能是內(nèi)置的如“文件讀寫”、“終端命令執(zhí)行”、“代碼分析”。而更強(qiáng)大的技能則來自MCP 集成。2.3 MCP 與外部工具集成MCP 是 CodeBuddy 能力擴(kuò)展的關(guān)鍵。它允許 CodeBuddy 連接外部服務(wù)器從而獲得新的“技能”。網(wǎng)絡(luò)熱詞中提到的codebuddy playwright mcp就是一個(gè)典型例子。playwright mcp集成后你可以直接對 CodeBuddy 說“為剛才創(chuàng)建的登錄頁面寫一個(gè) Playwright 測試并運(yùn)行它。” CodeBuddy 不僅能生成測試代碼還能通過 MCP 調(diào)用本地的 Playwright 環(huán)境來執(zhí)行測試并將結(jié)果反饋給你。這實(shí)現(xiàn)了從代碼生成到驗(yàn)證的閉環(huán)。其他 MCP理論上任何可以通過 MCP 協(xié)議暴露的工具都可以集成如數(shù)據(jù)庫客戶端、云服務(wù) CLI、內(nèi)部部署系統(tǒng)等。2.4 CodeBuddy vs. WorkBuddy網(wǎng)絡(luò)熱詞中頻繁出現(xiàn)兩者的對比。簡單區(qū)分CodeBuddy定位是開發(fā)者個(gè)人的 AI 結(jié)對編程助手深度集成在 VS Code 等 IDE 中核心場景是寫代碼、調(diào)試、理解項(xiàng)目。其“項(xiàng)目規(guī)則”聚焦于代碼本身的規(guī)范和上下文。WorkBuddy定位更偏向團(tuán)隊(duì)任務(wù)管理與自動(dòng)化協(xié)作可能集成在 Slack、Teams 等辦公工具中核心場景是管理工單、跟蹤進(jìn)度、協(xié)調(diào)資源。其“規(guī)則”可能更側(cè)重于工作流程和權(quán)限。對于開發(fā)者而言在 VS Code 中管理項(xiàng)目代碼CodeBuddy 是更直接和強(qiáng)大的選擇。本文討論的“項(xiàng)目規(guī)則”也特指 CodeBuddy 的范疇。3. 環(huán)境準(zhǔn)備與 CodeBuddy 基礎(chǔ)配置在創(chuàng)建規(guī)則之前你需要確保 CodeBuddy 已經(jīng)在你的開發(fā)環(huán)境中正確運(yùn)行。3.1 安裝 CodeBuddyCodeBuddy 主要作為 VS Code 擴(kuò)展提供。打開 VS Code。進(jìn)入擴(kuò)展市場 (CtrlShiftX)。搜索CodeBuddy。找到官方擴(kuò)展并點(diǎn)擊安裝。3.2 配置 API Key網(wǎng)絡(luò)熱詞中提到了vscode中如何通過apikey使用codebuddy。CodeBuddy 通常需要一個(gè)大模型 API Key 來驅(qū)動(dòng)如 OpenAI GPT, Anthropic Claude 等。安裝擴(kuò)展后VS Code 側(cè)邊欄會(huì)出現(xiàn) CodeBuddy 圖標(biāo)。點(diǎn)擊圖標(biāo)通常會(huì)引導(dǎo)你進(jìn)行初始設(shè)置。在設(shè)置中找到API Configuration或類似選項(xiàng)。填入你從相應(yīng) AI 服務(wù)商處獲得的 API Key。重要確保你的網(wǎng)絡(luò)環(huán)境可以正常訪問該 API 服務(wù)。關(guān)于網(wǎng)絡(luò)連通性問題請遵守當(dāng)?shù)胤煞ㄒ?guī)和使用條款使用合規(guī)的互聯(lián)網(wǎng)服務(wù)。3.3 驗(yàn)證安裝與排查常見啟動(dòng)錯(cuò)誤安裝后嘗試在 VS Code 中喚出 CodeBuddy通常通過命令面板CtrlShiftP輸入CodeBuddy。如果遇到問題請檢查以下網(wǎng)絡(luò)高頻錯(cuò)誤問題missing jcef runtime codebuddy relies on jcef (java chromium embedded framework)這是一個(gè)常見的啟動(dòng)錯(cuò)誤?？赡茉駽odeBuddy 的某些 UI 組件依賴于 JCEF但你的 Java 環(huán)境或 VS Code 環(huán)境缺少必要的運(yùn)行時(shí)。排查與解決更新 VS Code 和 CodeBuddy 擴(kuò)展確保使用最新版本。檢查 Java 環(huán)境確保系統(tǒng)已安裝合適版本的 JDK如 JDK 11, 17。在終端輸入java -version驗(yàn)證。查閱官方文檔前往 CodeBuddy 的官方 GitHub 或文檔站查看針對此錯(cuò)誤的特定解決方案。有時(shí)可能需要手動(dòng)下載某個(gè)組件。簡化啟動(dòng)嘗試在 CodeBuddy 設(shè)置中禁用一些高級的圖形化功能看是否能繞過此錯(cuò)誤。完成以上基礎(chǔ)配置并成功啟動(dòng) CodeBuddy 后我們就可以開始為核心項(xiàng)目創(chuàng)建規(guī)則了。4. 實(shí)戰(zhàn)為 React 項(xiàng)目創(chuàng)建你的第一份projectRules.json讓我們以一個(gè)典型的現(xiàn)代前端項(xiàng)目為例創(chuàng)建一個(gè)完整的項(xiàng)目規(guī)則。假設(shè)我們有一個(gè)使用 Vite React TypeScript Tailwind CSS 的項(xiàng)目項(xiàng)目結(jié)構(gòu)如下my-react-app/ ├── .codebuddy/ # 我們準(zhǔn)備把規(guī)則文件放在這里 ├── src/ │ ├── components/ │ ├── pages/ │ ├── hooks/ │ ├── utils/ │ ├── types/ │ ├── App.tsx │ └── main.tsx ├── public/ ├── package.json ├── tsconfig.json ├── tailwind.config.js └── vite.config.ts4.1 創(chuàng)建規(guī)則文件在項(xiàng)目根目錄下創(chuàng)建.codebuddy文件夾如果不存在然后在該文件夾內(nèi)創(chuàng)建projectRules.json文件。// 文件路徑.codebuddy/projectRules.json { version: 1.0, project: { name: My React Dashboard, description: 一個(gè)使用 Vite React TypeScript Tailwind CSS 構(gòu)建的管理后臺(tái)前端項(xiàng)目。, techStack: [React 18, TypeScript 5.x, Vite, Tailwind CSS, React Router DOM] }, directoryStructure: { source: src/, description: 所有源代碼文件均位于 src 目錄下。, keyDirectories: [ { path: src/components, purpose: 存放可復(fù)用的 UI 組件。組件應(yīng)使用 PascalCase 命名如 Button.tsx。每個(gè)組件應(yīng)有自己的目錄包含索引文件、組件文件和樣式文件如果使用 CSS Modules。 }, { path: src/pages, purpose: 存放頁面級組件。與路由一一對應(yīng)。 }, { path: src/hooks, purpose: 存放自定義 React Hooks。應(yīng)以 use 開頭如 useLocalStorage.ts。 }, { path: src/utils, purpose: 存放工具函數(shù)。應(yīng)是純函數(shù)且做好單元測試。 }, { path: src/types, purpose: 存放 TypeScript 類型定義和接口。 } ], ignorePatterns: [node_modules, dist, build, .git] }, codeConventions: { language: typescript, rules: [ 使用函數(shù)式組件和 React Hooks除非有特殊理由否則避免使用類組件。, 組件 Props 必須使用 TypeScript 接口或類型進(jìn)行嚴(yán)格定義。, 優(yōu)先使用命名導(dǎo)出Named Export而非默認(rèn)導(dǎo)出Default Export。, 使用 ES6 語法如箭頭函數(shù)、解構(gòu)賦值、可選鏈?.。, 樣式方案主要使用 Tailwind CSS 工具類。對于復(fù)雜組件可搭配 CSS Modules文件命名為 *.module.css。禁止內(nèi)聯(lián) style 對象和全局 CSS 污染。, 狀態(tài)管理簡單的組件狀態(tài)使用 useState?？缃M件狀態(tài)使用 Context API。復(fù)雜場景預(yù)留 Redux Toolkit 集成可能但當(dāng)前項(xiàng)目未安裝。, HTTP 客戶端使用 axios 進(jìn)行 API 調(diào)用。所有請求應(yīng)封裝在 src/services/ 目錄下的模塊中。, 路由使用 React Router DOM。路由定義應(yīng)集中管理。 ] }, dependencyManagement: { packageManager: npm, lockFile: package-lock.json, keyDependencies: { react: ^18.2.0, react-dom: ^18.2.0, typescript: ~5.2.0, types/react: ^18.2.0, axios: ^1.6.0, react-router-dom: ^6.20.0 } }, taskTemplates: [ { name: 創(chuàng)建新組件, steps: [ 1. 在 src/components 下創(chuàng)建以組件名命名的文件夾PascalCase。, 2. 在該文件夾內(nèi)創(chuàng)建 index.ts 文件用于導(dǎo)出組件。, 3. 創(chuàng)建 ComponentName.tsx 文件作為主組件。, 4. 如果需要樣式創(chuàng)建 ComponentName.module.css 文件。, 5. 在組件文件中定義 Props 接口實(shí)現(xiàn)函數(shù)式組件使用 Tailwind 類名。, 6. 在 index.ts 中導(dǎo)出組件。 ] }, { name: 添加新頁面及路由, steps: [ 1. 在 src/pages 下創(chuàng)建頁面組件文件如 UserProfile.tsx。, 2. 在路由配置文件如 src/router/index.tsx中導(dǎo)入該頁面組件并添加到路由數(shù)組中。, 3. 確保路由路徑符合 RESTful 約定。 ] } ], restrictions: [ 禁止直接操作 DOM如 document.getElementById必須使用 React 的 ref 或狀態(tài)驅(qū)動(dòng)。, 禁止在組件內(nèi)部或服務(wù)模塊中硬編碼 API 基礎(chǔ) URL。應(yīng)從環(huán)境變量 VITE_API_BASE_URL 讀取。, 禁止提交包含 console.log 調(diào)試語句的代碼請使用調(diào)試器或移除。, 所有對外部 API 的調(diào)用必須進(jìn)行錯(cuò)誤處理try-catch 或 .catch。 ] }4.2 規(guī)則文件詳解project為 AI 提供項(xiàng)目背景幫助它理解項(xiàng)目的宏觀目標(biāo)。directoryStructure這是最立竿見影的部分。明確目錄用途后當(dāng)你讓 AI “創(chuàng)建一個(gè)用戶頭像組件”它會(huì)毫不猶豫地放到src/components/Avatar下而不是別處。codeConventions定義了代碼的“法律”。它強(qiáng)制 AI 生成的代碼符合團(tuán)隊(duì)規(guī)范極大減少代碼審查時(shí)的風(fēng)格沖突。dependencyManagement防止 AI 建議安裝項(xiàng)目未聲明或版本不兼容的包。taskTemplates將常見工作流固化。AI 在執(zhí)行“創(chuàng)建組件”任務(wù)時(shí)會(huì)遵循這些步驟確保產(chǎn)出結(jié)構(gòu)一致。restrictions設(shè)定安全與質(zhì)量紅線。這是防止 AI 引入低級錯(cuò)誤或安全漏洞的關(guān)鍵。保存這個(gè)文件后CodeBuddy 在分析你的項(xiàng)目時(shí)就會(huì)加載這些規(guī)則。你可以立即嘗試在 VS Code 中打開項(xiàng)目對 CodeBuddy 說“在src/components下創(chuàng)建一個(gè)Button組件包含 primary 和 secondary 兩種變體?！?觀察生成的代碼你會(huì)發(fā)現(xiàn)它更有可能遵循你定義的 TypeScript 接口、Tailwind 類名規(guī)范和目錄結(jié)構(gòu)。5. 進(jìn)階集成 MCP 技能以 Playwright 為例現(xiàn)在讓我們?yōu)轫?xiàng)目添加自動(dòng)化測試能力。我們將集成playwright mcp讓 CodeBuddy 不僅能寫測試還能運(yùn)行測試。5.1 安裝 Playwright MCP 服務(wù)器首先你需要確保 Playwright MCP 服務(wù)器可用。這通常是一個(gè)獨(dú)立的進(jìn)程或服務(wù)。具體安裝方式需參考codebuddy-playwright-mcp的官方文檔。假設(shè)你已經(jīng)通過 npm 全局安裝或克隆了相關(guān)倉庫。# 假設(shè)安裝方式是通過 npm請以實(shí)際 MCP 包名為準(zhǔn) npm install -g codebuddy/playwright-mcp-server5.2 配置 CodeBuddy 連接 MCP接下來需要在 CodeBuddy 的配置中告知它這個(gè) MCP 服務(wù)器的位置。配置可能位于 VS Code 的用戶設(shè)置 (settings.json) 或 CodeBuddy 的專屬配置文件中。// 文件路徑.vscode/settings.json 或 CodeBuddy 配置界面 { codebuddy.mcpServers: { playwright: { command: npx, args: [codebuddy/playwright-mcp-server], env: { // 可選的環(huán)境變量 } } } }5.3 在項(xiàng)目規(guī)則中聲明技能然后在你的projectRules.json中可以添加一個(gè)skills或mcpIntegrations部分聲明本項(xiàng)目可用的高級技能。// 在 .codebuddy/projectRules.json 中添加 { // ... 之前的配置保持不變 ... mcpIntegrations: [ { name: playwright, description: 用于端到端E2E測試?？梢跃帉?、運(yùn)行和調(diào)試 Playwright 測試腳本。, capabilities: [ generate_e2e_test, run_test, inspect_page ] } ], taskTemplates: [ // ... 原有的任務(wù)模板 ... { name: 為頁面生成并運(yùn)行 E2E 測試, steps: [ 1. 使用 Playwright MCP 技能分析目標(biāo)頁面如 /login的 DOM 結(jié)構(gòu)。, 2. 在 tests/e2e/ 目錄下生成一個(gè) Playwright 測試文件如 login.spec.ts。, 3. 測試應(yīng)包含頁面導(dǎo)航、元素定位、交互輸入、點(diǎn)擊和斷言。, 4. 使用 Playwright MCP 技能運(yùn)行生成的測試并報(bào)告結(jié)果。 ], requiredSkill: playwright } ] }5.4 使用技能配置完成后你可以向 CodeBuddy 發(fā)出更強(qiáng)大的指令“為我們的登錄頁面/login生成一個(gè) Playwright E2E 測試檢查用戶輸入錯(cuò)誤密碼時(shí)的提示信息并運(yùn)行這個(gè)測試?！盋odeBuddy 會(huì)理解你的項(xiàng)目規(guī)則知道測試文件應(yīng)放在tests/e2e/。調(diào)用 Playwright MCP 技能分析登錄頁面的實(shí)際元素。生成符合項(xiàng)目代碼規(guī)范的測試腳本。再次調(diào)用 MCP 技能在后臺(tái)啟動(dòng)瀏覽器運(yùn)行測試并將成功或失敗的結(jié)果反饋給你。這就實(shí)現(xiàn)了從需求到驗(yàn)證的自動(dòng)化閉環(huán)極大地提升了前端測試的效率和可靠性。6. 運(yùn)行驗(yàn)證與效果評估如何驗(yàn)證你的項(xiàng)目規(guī)則是否生效可以通過幾個(gè)簡單的測試測試 1目錄結(jié)構(gòu)遵從性指令“創(chuàng)建一個(gè)顯示用戶列表的組件叫UserTable。”預(yù)期結(jié)果在src/components/UserTable/目錄下生成index.ts和UserTable.tsx文件。驗(yàn)證檢查生成的文件路徑是否正確。測試 2代碼規(guī)范遵從性指令“在UserTable組件里添加一個(gè)從/api/users獲取數(shù)據(jù)的函數(shù)?！鳖A(yù)期結(jié)果生成的函數(shù)使用axios。API URL 不是硬編碼而是使用了VITE_API_BASE_URL環(huán)境變量根據(jù)規(guī)則。函數(shù)被放在一個(gè)useEffect或自定義 Hook 中并有錯(cuò)誤處理。驗(yàn)證檢查生成的代碼片段是否符合restrictions和codeConventions中的規(guī)則。測試 3任務(wù)模板觸發(fā)指令“按照‘創(chuàng)建新組件’的流程做一個(gè)Modal對話框組件。”預(yù)期結(jié)果AI 的回復(fù)或生成的文件結(jié)構(gòu)會(huì)清晰地反映出任務(wù)模板中定義的步驟。驗(yàn)證觀察 AI 的思考過程或輸出是否結(jié)構(gòu)化。如果測試結(jié)果不符合預(yù)期請進(jìn)入下一節(jié)的排查環(huán)節(jié)。7. 常見問題與排查思路以下是基于網(wǎng)絡(luò)討論和實(shí)際使用中可能遇到的問題匯總問題現(xiàn)象可能原因排查方式解決方案CodeBuddy 完全忽略項(xiàng)目規(guī)則行為像沒配置一樣。1. 規(guī)則文件路徑錯(cuò)誤或文件名不對。2. 規(guī)則文件 JSON 格式有語法錯(cuò)誤。3. CodeBuddy 未正確加載項(xiàng)目上下文。1. 檢查.codebuddy/projectRules.json文件是否存在且路徑正確。2. 使用 JSON 驗(yàn)證工具檢查文件語法。3. 在 VS Code 中確保打開的是項(xiàng)目根目錄并重啟 CodeBuddy 面板。1. 確保文件在正確位置。2. 修正 JSON 語法錯(cuò)誤。3. 重啟 VS Code 或重新加載 CodeBuddy 擴(kuò)展。AI 生成的代碼風(fēng)格與規(guī)則不符如用了類組件。1. 規(guī)則描述不夠具體或存在歧義。2. AI 的底層模型未能完全理解規(guī)則。3. 規(guī)則與其他指令沖突。1. 檢查codeConventions.rules是否表述清晰。例如明確寫“禁止使用類組件”。2. 在指令中更明確地強(qiáng)調(diào)規(guī)則如“請嚴(yán)格遵守項(xiàng)目規(guī)則中關(guān)于使用函數(shù)式組件的規(guī)定”。1. 細(xì)化規(guī)則描述使用肯定/否定句明確要求。2. 結(jié)合指令明確約束。規(guī)則是一個(gè)強(qiáng)提示并非絕對強(qiáng)制。集成 MCP如 Playwright失敗AI 說找不到該技能。1. MCP 服務(wù)器未啟動(dòng)或命令配置錯(cuò)誤。2. CodeBuddy 配置中 MCP 服務(wù)器路徑不正確。3. 項(xiàng)目規(guī)則中mcpIntegrations聲明有誤。1. 手動(dòng)在終端嘗試啟動(dòng) MCP 服務(wù)器命令看是否報(bào)錯(cuò)。2. 檢查settings.json中codebuddy.mcpServers的配置。3. 確認(rèn)項(xiàng)目規(guī)則中技能名稱與配置的服務(wù)器名稱匹配。1. 根據(jù) MCP 服務(wù)器文檔確保其正確安裝和運(yùn)行。2. 修正 VS Code 或 CodeBuddy 的配置。3. 確保規(guī)則文件中的技能聲明準(zhǔn)確。遇到missing jcef runtime錯(cuò)誤無法啟動(dòng) CodeBuddy UI。CodeBuddy 的圖形界面依賴 JCEF 組件缺失或版本不兼容。1. 查看完整錯(cuò)誤日志。2. 檢查 VS Code 版本和 CodeBuddy 擴(kuò)展版本。1.首選更新 VS Code 和 CodeBuddy 擴(kuò)展至最新版。2. 根據(jù)官方 Issue 或文檔可能需要安裝特定版本的 JDK 或手動(dòng)下載 JCEF 庫。3.臨時(shí)方案在設(shè)置中嘗試禁用 CodeBuddy 的某些可視化功能。AI 對項(xiàng)目目錄的理解仍然有偏差。directoryStructure描述不夠詳細(xì)或者項(xiàng)目存在非常規(guī)結(jié)構(gòu)。讓 AI 描述它當(dāng)前理解的項(xiàng)目結(jié)構(gòu)。在規(guī)則文件中為每個(gè)重要目錄添加更詳細(xì)的purpose描述。對于復(fù)雜項(xiàng)目可以考慮提供一個(gè)簡化的架構(gòu)圖說明。如何領(lǐng)取或使用codebuddy積分“積分”可能指某些云服務(wù)或商業(yè)版的額度/點(diǎn)數(shù)系統(tǒng)。查閱 CodeBuddy 的官方定價(jià)、訂閱或活動(dòng)頁面。這通常與本地項(xiàng)目規(guī)則配置無關(guān)。請參考 CodeBuddy 官方網(wǎng)站或訂閱郵件獲取相關(guān)信息。8. 最佳實(shí)踐與工程建議為了讓項(xiàng)目規(guī)則發(fā)揮最大效用并使其易于維護(hù)請遵循以下建議版本化規(guī)則文件將.codebuddy/projectRules.json納入版本控制系統(tǒng)如 Git。這樣團(tuán)隊(duì)所有成員都使用同一套規(guī)則保證了協(xié)作的一致性。漸進(jìn)式完善不要試圖一次性寫出完美的規(guī)則。從最痛的痛點(diǎn)開始比如目錄結(jié)構(gòu)然后隨著使用逐步添加代碼規(guī)范、任務(wù)模板和限制項(xiàng)。規(guī)則描述具體化避免使用“代碼要整潔”這類模糊描述。使用具體、可執(zhí)行的語句如“函數(shù)長度不應(yīng)超過50行”、“React 組件必須使用React.memo進(jìn)行性能優(yōu)化如果合適”。區(qū)分強(qiáng)制與推薦在restrictions中放置必須遵守的條款如安全紅線。在codeConventions中放置強(qiáng)烈推薦的規(guī)范?？梢栽谧⑨屩姓f明原因。為多模塊項(xiàng)目配置對于大型 Monorepo 或微服務(wù)項(xiàng)目可以在根目錄設(shè)置通用規(guī)則然后在子模塊的.codebuddy目錄下配置更具體的規(guī)則。CodeBuddy 通常會(huì)合并或就近應(yīng)用規(guī)則。定期復(fù)審規(guī)則技術(shù)棧和團(tuán)隊(duì)規(guī)范會(huì)演進(jìn)。每個(gè)季度或半年團(tuán)隊(duì)?wèi)?yīng)一起復(fù)審項(xiàng)目規(guī)則更新過時(shí)的約定添加新的最佳實(shí)踐。結(jié)合代碼檢查工具項(xiàng)目規(guī)則是給 AI 看的“軟約束”。還應(yīng)配置 ESLint、Prettier、SonarQube 等工具作為“硬約束”在 CI/CD 流水線中自動(dòng)執(zhí)行形成雙重保障。安全第一restrictions部分是設(shè)置安全邊界的關(guān)鍵。務(wù)必包含禁止硬編碼密碼/密鑰、禁止危險(xiǎn)的數(shù)據(jù)庫操作、禁止引入已知高危依賴等條款。通過創(chuàng)建和維護(hù)一個(gè)精良的projectRules.json文件你不僅僅是在配置一個(gè)工具更是在為你的項(xiàng)目定義一份活的、可執(zhí)行的開發(fā)憲法。它讓 CodeBuddy 這個(gè)強(qiáng)大的 AI 助手真正融入了你的技術(shù)棧和團(tuán)隊(duì)文化從“能寫代碼”進(jìn)化到“能寫好這個(gè)項(xiàng)目的代碼”。最終衡量項(xiàng)目規(guī)則成功與否的標(biāo)準(zhǔn)很簡單當(dāng)你給 AI 一個(gè)任務(wù)后不再需要反復(fù)糾正它的基礎(chǔ)錯(cuò)誤而是可以專注于討論更復(fù)雜的邏輯和架構(gòu)設(shè)計(jì)。這時(shí)你就已經(jīng)跨越了人機(jī)協(xié)作的第一個(gè)重要門檻。