1. 项目概述为你的AI编程助手定制“大脑”如果你用过GitHub Copilot、Cursor或者Claude Code这类AI编程助手大概率有过这样的体验它生成的代码风格飘忽不定有时能精准地写出你想要的业务逻辑有时却连基本的项目结构都搞不清楚。这背后的核心原因是这些工具缺乏对你当前项目的“上下文理解”。它们不知道你用的是Flask还是FastAPI不清楚你的团队是推崇DDD还是MVC更不了解你项目中那些不成文的代码规范。这个名为“AI Coding Assistant Instructions Generator”的项目就是为了解决这个问题而生的。你可以把它理解为一个“AI助手指令定制工厂”。它的核心功能非常简单根据你项目的具体特性如编程语言、框架、项目类型、开发原则动态生成一份高度定制化的“指导手册”Instructions然后让你把这本手册“喂”给你的AI编程助手。一旦助手“读”懂了这本手册它生成的代码就会立刻变得“懂行”起来——命名规范、架构风格、甚至文件组织方式都会无限贴近你的实际需求。它不是一个需要安装的软件而是一个开源的、基于Web的工具。无论你是前端开发者、后端工程师还是数据科学家只要你的项目需要写代码并且你希望AI助手能更“聪明”地辅助你这个工具就值得一试。接下来我会带你深入拆解它的设计思路、手把手教你如何使用并分享我在实际集成过程中踩过的坑和总结出的高效技巧。2. 核心设计思路模块化与动态组合这个项目的设计非常巧妙它没有试图创建一个庞大而僵化的“万能指令集”而是采用了一种“乐高积木”式的模块化架构。理解这个设计是高效使用它的关键。2.1 单一信息源原则项目最核心的目录是copilot-instructions-templates/。这里面存放着所有原始的、模块化的指令模板它们是整个系统的“单一信息源”。这个目录结构清晰地反映了其设计哲学copilot-instructions-templates/ ├── core/ # 基础原则适用于所有项目 ├── languages/ # 语言/框架特定规范 └── project-types/ # 项目类型特定要求core/目录这里定义的是放之四海而皆准的软件开发最佳实践。例如它会强调“禁止硬编码字符串必须使用常量或枚举”、“遵循关注点分离原则业务逻辑、数据访问和UI展示要清晰分层”。无论你写Python还是Java做Web应用还是CLI工具这些原则都应该被遵守。这是你AI助手的“基础教育”。languages/目录这里是“专业技能培训”。当你选择“Python - FastAPI”时系统会从这里抽取对应的模块告诉AI助手“在这个项目里路由要定义在apis/目录下依赖注入要这么用Pydantic模型应该这样写。” 它让助手掌握了特定技术栈的“方言”。project-types/目录这里提供的是“行业知识”。一个“数据科学”项目和一个“Web应用程序”项目代码的组织方式和关注点截然不同。这个目录的模块会指导AI助手“如果是数据分析项目请优先使用pandas DataFrame并给出数据预览如果是Web API项目请确保每个端点都有清晰的输入输出验证。”设计精妙之处这种分离确保了指令的维护性。如果你想更新所有Python项目的代码风格只需修改languages/python.md如果你想增加对Rust语言的支持也只需在languages/下新增一个文件。Web界面docs/只是一个“组装车间”它读取这些模块并根据用户的选择进行动态组合和渲染。2.2 Web生成器可视化的指令装配线项目提供的Web界面docs/index.html是整个系统的用户体验层。它的作用是将背后的模块化模板转化成一个对用户友好的图形化表单。其工作流程可以概括为加载与解析页面加载时JavaScript引擎template-generator.js会去读取copilot-instructions-templates/下的各个Markdown模板文件。分类与映射引擎解析模板内容将其分类为“核心原则”、“语言/框架”、“项目类型”等选项并动态生成网页上的复选框、下拉菜单。动态组装当你在界面上勾选“Python”、“FastAPI”、“Web应用程序”时引擎会实时地将对应的core/basic-principles.md、languages/python-fastapi.md、project-types/web-application.md这几个文件的内容拼接在一起。预览与输出组装好的完整指令会即时显示在预览框中并提供一个“一键复制”按钮。你复制的内容就是一份为你当前项目量身定制的、立即可用的AI助手指导手册。这种设计的好处是“开箱即用”。你不需要懂任何模板语法也不需要手动编辑文件通过点选就能完成复杂指令的定制。同时因为所有模板是纯文本的Markdown高级用户也可以直接克隆仓库手动编辑或组合这些模板灵活性极高。3. 从零开始手把手配置你的AI助手了解了原理我们来看具体怎么用。我将以最常见的两个场景——使用Cursor和GitHub Copilot——为例展示完整的配置流程。3.1 第一步生成你的专属指令无论你后续用哪个工具第一步都是相同的打开Web生成器定制指令。访问生成器在浏览器中打开https://yulikepython.github.io/ai-coding-assistant-instructions-generator/。这是一个静态页面无需任何后端服务打开即用。填写项目信息在“Project Info”部分简要描述你的项目。例如“一个基于FastAPI的用户管理系统使用SQLAlchemy ORM和Pydantic进行数据验证。” 这有助于生成更贴切的指令引言。选择开发环境根据你的操作系统选择Linux/macOS (bash) 或 Windows (PowerShell)。这会影响生成的命令行操作示例。勾选编程语言与框架这是最关键的一步。假设你的项目是“FastAPI后端 React前端”那么你应该勾选Python-FastAPIJavaScript/TypeScript-React如果前端使用了SCSS还可以勾选SCSS选项。选择项目类型根据项目性质选择例如Web Application。应用开发原则建议将core/下的所有原则如Domain-Driven Design Concepts, Separation of Concerns, Avoid Hardcoding Strings全部勾选。这些都是良好的编程习惯让AI助手从一开始就遵循高标准。生成并复制点击“Generate Instructions”按钮。右侧预览区会立刻出现一份完整的、格式清晰的Markdown指令文档。点击“Copy to Clipboard”按钮复制全部内容。至此你的“AI助手培训手册”已经准备好了。接下来就是把它“安装”到具体的工具里。3.2 第二步为Cursor配置规则Cursor是目前对自定义指令支持最友好、效果最显著的AI IDE之一。它通过项目根目录下的一个名为.cursorrules的文件来读取指令。定位项目根目录打开你的终端或命令行使用cd命令进入你的项目根目录。创建或编辑规则文件# 如果已有 .cursorrules 文件则编辑它 nano .cursorrules # 或使用你喜欢的编辑器如 code .cursorrules, vim .cursorrules 等粘贴指令将第一步中复制的内容完整地粘贴到.cursorrules文件中然后保存退出。立即生效无需重启Cursor只要该文件被保存Cursor的AI助手无论是使用Claude还是GPT模型在分析你这个项目的上下文时就会自动遵循.cursorrules文件中的所有指令。实操心得.cursorrules的威力我曾在一個既有Django後端又有Vue前端的全棧項目中測試。配置前讓Cursor“創建一個用戶詳情API”它可能會生成一個混雜了ORM操作和HTML響應的視圖。配置了詳細的指令後它清晰地將請求路由到api/views.py在serializers.py中定義序列化器並在services.py中編寫業務邏輯完全符合後端項目的分層架構。對於前端請求它也會自動生成使用Axios的、帶有錯誤處理的Vue 3 Composition API代碼。這種上下文感知能力大大減少了後續重構的工作量。3.3 第三步为GitHub Copilot配置指令GitHub Copilot在IDE中如VS Code通常以全局方式工作。但從2023年開始它支持了倉庫級別或目錄級別的指令配置這讓項目特定指令成為可能。創建指令目錄在你的項目根目錄下創建.github文件夾如果不存在。mkdir -p .github創建指令文件在.github文件夾內創建一個名為copilot-instructions.md的文件。nano .github/copilot-instructions.md粘貼指令同樣將Web生成器生成的指令內容粘貼到這個文件中並保存。確保Copilot讀取根據GitHub官方文檔Copilot會自動在項目中尋找此路徑下的此文件。但為了確保生效建議重啟你的VS Code或其它安裝了Copilot的IDE。在VS Code中打開命令面板CtrlShiftP或CmdShiftP輸入GitHub Copilot: Enable Local Instructions並執行確保該功能已啟用。注意事項文件位置與優先級根據我的測試copilot-instructions.md文件必須放在.github/目錄下且文件名必須完全一致。Copilot會優先使用項目級指令如果沒有找到則會回退到用戶全局設置的指令。這意味著你可以為不同的項目設置完全不同的編碼規範互不干擾。3.4 第四步為Claude Code配置指令如果你在VS Code中使用的是Anthropic官方推出的Claude Code擴展配置方式略有不同因為它將指令作為擴展設置的一部分。打開項目設置在你的項目根目錄下創建或打開.vscode/settings.json文件。# 創建 .vscode 目錄和設置文件 mkdir -p .vscode nano .vscode/settings.json添加Claude指令配置在settings.json文件中添加一個特定的配置項。注意這裡的指令內容需要以一個長字符串的形式放入。{ claude.instructions: 請將此處替換為你從生成器複製的、完整的指令文本。注意這裡需要將整個Markdown內容作為一個字符串確保換行符被正確轉義。 }實際上更穩妥的做法是使用工具或仔細地將多行Markdown轉換為一個合法的JSON字符串。一個更簡單的方法是直接使用Web生成器為Claude Code提供的專用格式。在項目的Web界面上生成指令後有時會提供針對不同工具的格式化輸出選項請留意查看複製按鈕附近的提示。如果沒有則需要手動處理引號和換行符。常見問題Claude Code指令不生效這是配置Claude Code時最常見的坑。問題通常出在settings.json的JSON格式上。多行字符串中的雙引號必須被轉義為\換行符也需處理。一個實用的技巧是先將指令內容粘貼到一個在線的“JSON字符串轉義”工具中進行處理然後再將處理後的結果放入claude.instructions的值中。或者你也可以考慮將指令寫在一個單獨的.clauderc或claude_instructions.md文件中然後在settings.json中通過文件路徑引用如果擴展支持此方式具體需查閱Claude Code擴展的最新文檔。4. 高級用法與模板深度定制對於大多數用戶使用Web界面生成指令已經足夠。但如果你所在團隊有極其特殊的規範或者你想貢獻新的語言模板那麼就需要深入了解模板系統並進行本地開發。4.1 本地運行與調試如果你想修改模板或添加新功能首先需要在本地搭建環境。克隆倉庫git clone https://github.com/Yulikepython/ai-coding-assistant-instructions-generator.git cd ai-coding-assistant-instructions-generator運行本地服務器項目使用一個簡單的Python HTTP服務器來提供Web界面。cd docs python3 -m http.server 8000 # 對於Python 2.x使用python -m SimpleHTTPServer 8000訪問本地界面打開瀏覽器訪問http://localhost:8000。你現在對docs/或copilot-instructions-templates/目錄下的任何修改刷新頁面後都會立即體現在本地Web界面上。4.2 解剖一個模板文件讓我們以copilot-instructions-templates/languages/python-fastapi.md為例看看一個好的指令模板應該包含什麼。## Python (FastAPI) 項目規範 ### 架構與文件組織 - 使用 app/main.py 作為應用程序入口點。 - 路由定義應放在 app/api/ 目錄下的獨立模塊中例如 app/api/items.py。 - 數據模型Pydantic定義在 app/schemas/ 目錄。 - 數據庫模型SQLAlchemy定義在 app/models/ 目錄。 - 核心業務邏輯應封裝在 app/services/ 或 app/crud/ 目錄。 - 工具函數和依賴項放在 app/core/ 和 app/dependencies/。 ### 代碼風格與實踐 - 所有路徑操作函數必須是 async def。 - 使用Pydantic模型進行請求/響應數據的驗證和序列化。 - 依賴注入應優先使用 Depends()避免全局狀態。 - 錯誤處理應使用HTTPException並提供清晰的錯誤信息。 - 為所有路徑操作添加清晰的操作摘要summary和描述description。 ### 示例模式 當被要求創建一個新的API端點時應按以下模式生成代碼 1. 在 app/schemas/ 創建對應的Pydantic模型如 ItemCreate, ItemUpdate, ItemResponse。 2. 在 app/api/ 下創建或更新路由文件。 3. 在路由函數中定義參數、依賴和響應模型。 4. 引用服務層或CRUD層的函數來處理業務邏輯。可以看到一個有效的模板不僅是規則的羅列更是模式Pattern和範例Example的傳授。它告訴AI助手“應該怎麼做”並通過示例展示“好的代碼長什麼樣”。這比單純說“寫出高質量的代碼”要有效得多。4.3 如何貢獻一個新的語言模板假設你想為Go語言使用Gin框架添加支持。創建模板文件在copilot-instructions-templates/languages/目錄下新建一個go-gin.md文件。編寫模板內容參考現有模板的結構編寫針對GoGin的規範。## Go (Gin) 項目規範 ### 項目布局 - 採用 cmd/, internal/, pkg/, api/, configs/ 標準布局。 - 路由定義在 internal/router/ 或 api/routes.go。 - 控制器Handler放在 internal/handler/。 - 業務邏輯放在 internal/service/。 - 數據模型放在 internal/model/。 ### 編碼約定 - 使用 c *gin.Context 作為處理函數的接收器。 - 錯誤處理應統一返回使用自定義的錯誤響應結構體。 - 必須為所有導出的函數、結構體添加Godoc注釋。更新Web生成器邏輯編輯docs/template-generator.js文件。你需要找到定義語言選項的數組或對象通常是一個名為LANGUAGES的常量在其中添加{id: go-gin, label: Go (Gin), file: languages/go-gin.md}。本地測試運行本地服務器在Web界面上檢查Go (Gin)選項是否出現勾選後生成的指令是否包含了你的新模板內容。提交Pull Request測試無誤後將你的修改推送到你Fork的倉庫並向原倉庫發起Pull Request。5. 實戰技巧與疑難排解經過在多個真實項目中的集成和使用我總結出一些能讓這個工具發揮最大效能的技巧以及常見問題的解決方法。5.1 讓指令更有效的三個技巧從簡到繁迭代配置不要一開始就勾選所有選項。先從最核心的語言和項目類型開始。讓AI助手適應基本規範後再逐步添加“DDD原則”、“嚴格的錯誤處理”等高級要求。這可以避免指令過於複雜導致AI理解混亂。在指令中嵌入“活文檔”你可以在Web生成器的“Project Info”框或通過直接編輯模板加入你項目特有的約定。例如“本項目使用uuid作為所有數據表的主鍵請勿使用自增ID。” 或者 “所有API響應必須包裹在{code: number, data: T, message: string}的結構中。” 這能極大提升生成代碼的可用性。結合工具的自定義指令Cursor和Copilot通常也允許在聊天框或評論中編寫一次性指令。你可以將生成的核心指令如架構規範放在配置文件中而將當前正在編寫的模塊的具體要求如“請為UserService實現一個根據郵件模糊查詢並分頁的方法”作為即時指令輸入。長效配置與短效上下文結合效果最佳。5.2 常見問題速查表問題現象可能原因解決方案Cursor完全無視.cursorrules1. 文件不在項目根目錄。2. 文件名拼寫錯誤必須是.cursorrules。3. Cursor版本過舊。1. 使用pwd和ls -la確認文件位置。2. 檢查文件名注意開頭的點號。3. 更新Cursor到最新版本。Copilot行為未改變1.copilot-instructions.md路徑或文件名錯誤。2. 未重啟IDE或重載窗口。3. 全局指令覆蓋了項目指令。1. 確認文件路徑為.github/copilot-instructions.md。2. 重啟VS Code或執行Developer: Reload Window命令。3. 檢查VS Code設置中github.copilot.advanced下的指令是否為空。生成的指令太長AI似乎記不住所有AI模型都有上下文長度限制。過長的指令可能導致後半部分被忽略。精簡指令只保留最關鍵、最通用的規則。將非常具體的規則移到項目的README或通過即時對話提供。優先保留架構約束和代碼風格可以適當減少示例代碼。指令間存在衝突例如同時選擇了“DDD”和“簡單的MVC”AI可能無所適從。確保你選擇的模塊在哲學上是一致的。通常core/下的原則是基礎languages/和project-types/的選擇應與之協調。對於複雜項目可能需要手動編輯合併後的指令消除矛盾點。Web界面無法加載或空白1. 本地服務器未正確啟動。2. 瀏覽器緩存問題。3. JavaScript加載錯誤。1. 檢查終端是否在docs目錄下運行http.server並無報錯。2. 嘗試瀏覽器無痕模式訪問。3. 打開瀏覽器開發者工具F12查看“控制台(Console)”有無紅色錯誤信息。5.3 效果評估與調優配置完成後如何知道指令是否真的起作用了一個簡單的測試方法是向AI助手提出一個具有明確架構指向性的問題。例如在一個配置了FastAPI指令的項目中你可以直接對Cursor說“請創建一個用於管理圖書的CRUD API。” 觀察其生成的代碼成功跡象它會自動創建schemas/book.py、api/books.py並在main.py中引入路由使用的代碼風格完全符合Pydantic和FastAPI的最佳實踐。失敗跡象它可能把所有代碼都堆在一個文件裡或者使用了錯誤的異步風格。如果效果不理想回到Web生成器復盤你選擇的選項。是不是“項目類型”選錯了或者某個語言特定的規範模板寫得不夠清晰這時本地開發和調試的能力就派上用場了。你可以直接修改對應的模板文件加入更明確的示例然後在本地測試直到AI給出你滿意的答案為止。這個過程本身也是一種對團隊編碼規範的梳理和沉澱。最終你不僅得到了一個更聰明的AI編程夥伴也得到了一份不斷演進的、機器可讀的項目開發規範文檔。