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 ）是整个系统的用户体验层。它的作用是将背后的模块化模板，转化成一个对用户友好的图形化表单。

其工作流程可以概括为：

1. 加载与解析 ：页面加载时，JavaScript引擎（ template-generator.js ）会去读取 copilot-instructions-templates/ 下的各个Markdown模板文件。
2. 分类与映射 ：引擎解析模板内容，将其分类为“核心原则”、“语言/框架”、“项目类型”等选项，并动态生成网页上的复选框、下拉菜单。
3. 动态组装 ：当你在界面上勾选“Python”、“FastAPI”、“Web应用程序”时，引擎会实时地将对应的 core/basic-principles.md 、 languages/python-fastapi.md 、 project-types/web-application.md 这几个文件的内容拼接在一起。
4. 预览与输出 ：组装好的完整指令会即时显示在预览框中，并提供一个“一键复制”按钮。你复制的内容，就是一份为你当前项目量身定制的、立即可用的AI助手指导手册。

这种设计的好处是“开箱即用”。你不需要懂任何模板语法，也不需要手动编辑文件，通过点选就能完成复杂指令的定制。同时，因为所有模板是纯文本的Markdown，高级用户也可以直接克隆仓库，手动编辑或组合这些模板，灵活性极高。

3. 从零开始：手把手配置你的AI助手

了解了原理，我们来看具体怎么用。我将以最常见的两个场景——使用Cursor和GitHub Copilot——为例，展示完整的配置流程。

3.1 第一步：生成你的专属指令

无论你后续用哪个工具，第一步都是相同的：打开Web生成器，定制指令。

1. 访问生成器 ：在浏览器中打开 https://yulikepython.github.io/ai-coding-assistant-instructions-generator/ 。这是一个静态页面，无需任何后端服务，打开即用。
2. 填写项目信息 ：在“Project Info”部分，简要描述你的项目。例如：“一个基于FastAPI的用户管理系统，使用SQLAlchemy ORM和Pydantic进行数据验证。” 这有助于生成更贴切的指令引言。
3. 选择开发环境 ：根据你的操作系统，选择Linux/macOS (bash) 或 Windows (PowerShell)。这会影响生成的命令行操作示例。
4. 勾选编程语言与框架 ：这是最关键的一步。假设你的项目是“FastAPI后端 + React前端”，那么你应该勾选：
   • Python -> FastAPI
   • JavaScript/TypeScript -> React
   • 如果前端使用了SCSS，还可以勾选 SCSS 选项。
5. 选择项目类型 ：根据项目性质选择，例如 Web Application 。
6. 应用开发原则 ：建议将 core/ 下的所有原则（如Domain-Driven Design Concepts, Separation of Concerns, Avoid Hardcoding Strings）全部勾选。这些都是良好的编程习惯，让AI助手从一开始就遵循高标准。
7. 生成并复制 ：点击“Generate Instructions”按钮。右侧预览区会立刻出现一份完整的、格式清晰的Markdown指令文档。点击“Copy to Clipboard”按钮，复制全部内容。

至此，你的“AI助手培训手册”已经准备好了。接下来就是把它“安装”到具体的工具里。

3.2 第二步：为Cursor配置规则

Cursor是目前对自定义指令支持最友好、效果最显著的AI IDE之一。它通过项目根目录下的一个名为 .cursorrules 的文件来读取指令。

1. 定位项目根目录 ：打开你的终端或命令行，使用 cd 命令进入你的项目根目录。
2. 创建或编辑规则文件 ：

   # 如果已有 .cursorrules 文件，则编辑它
   nano .cursorrules
   # 或使用你喜欢的编辑器，如 code .cursorrules, vim .cursorrules 等
   

3. 粘贴指令 ：将第一步中复制的内容，完整地粘贴到 .cursorrules 文件中，然后保存退出。
4. 立即生效 ：无需重启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年開始，它支持了 倉庫級別 或 目錄級別 的指令配置，這讓項目特定指令成為可能。

1. 創建指令目錄 ：在你的項目根目錄下，創建 .github 文件夾（如果不存在）。

   mkdir -p .github
   

2. 創建指令文件 ：在 .github 文件夾內創建一個名為 copilot-instructions.md 的文件。

   nano .github/copilot-instructions.md
   

3. 粘貼指令 ：同樣，將Web生成器生成的指令內容粘貼到這個文件中並保存。
4. 確保Copilot讀取 ：根據GitHub官方文檔，Copilot會自動在項目中尋找此路徑下的此文件。但為了確保生效，建議：
   • 重啟你的VS Code（或其它安裝了Copilot的IDE）。
   • 在VS Code中，打開命令面板（ Ctrl+Shift+P 或 Cmd+Shift+P ），輸入 GitHub Copilot: Enable Local Instructions 並執行，確保該功能已啟用。

注意事項：文件位置與優先級 根據我的測試， copilot-instructions.md 文件必須放在 .github/ 目錄下，且文件名必須完全一致。Copilot會優先使用項目級指令，如果沒有找到，則會回退到用戶全局設置的指令。這意味著你可以為不同的項目設置完全不同的編碼規範，互不干擾。

3.4 第四步：為Claude Code配置指令

如果你在VS Code中使用的是Anthropic官方推出的Claude Code擴展，配置方式略有不同，因為它將指令作為擴展設置的一部分。

1. 打開項目設置 ：在你的項目根目錄下，創建或打開 .vscode/settings.json 文件。

   # 創建 .vscode 目錄和設置文件
   mkdir -p .vscode
   nano .vscode/settings.json
   

2. 添加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 本地運行與調試

如果你想修改模板或添加新功能，首先需要在本地搭建環境。

1. 克隆倉庫 ：

   git clone https://github.com/Yulikepython/ai-coding-assistant-instructions-generator.git
   cd ai-coding-assistant-instructions-generator
   

2. 運行本地服務器 ：項目使用一個簡單的Python HTTP服務器來提供Web界面。

   cd docs
   python3 -m http.server 8000
   # 對於Python 2.x，使用：python -m SimpleHTTPServer 8000
   

3. 訪問本地界面 ：打開瀏覽器，訪問 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框架）添加支持。

1. 創建模板文件 ：在 copilot-instructions-templates/languages/ 目錄下，新建一個 go-gin.md 文件。
2. 編寫模板內容 ：參考現有模板的結構，編寫針對Go+Gin的規範。

   ## Go (Gin) 項目規範
   ### 項目布局
   - 採用 `cmd/`, `internal/`, `pkg/`, `api/`, `configs/` 標準布局。
   - 路由定義在 `internal/router/` 或 `api/routes.go`。
   - 控制器（Handler）放在 `internal/handler/`。
   - 業務邏輯放在 `internal/service/`。
   - 數據模型放在 `internal/model/`。
   ### 編碼約定
   - 使用 `c *gin.Context` 作為處理函數的接收器。
   - 錯誤處理應統一返回，使用自定義的錯誤響應結構體。
   - 必須為所有導出的函數、結構體添加Godoc注釋。
   

3. 更新Web生成器邏輯 ：編輯 docs/template-generator.js 文件。你需要找到定義語言選項的數組或對象（通常是一個名為 LANGUAGES 的常量），在其中添加 {id: 'go-gin', label: 'Go (Gin)', file: 'languages/go-gin.md'} 。
4. 本地測試 ：運行本地服務器，在Web界面上檢查Go (Gin)選項是否出現，勾選後生成的指令是否包含了你的新模板內容。
5. 提交Pull Request ：測試無誤後，將你的修改推送到你Fork的倉庫，並向原倉庫發起Pull Request。

5. 實戰技巧與疑難排解

經過在多個真實項目中的集成和使用，我總結出一些能讓這個工具發揮最大效能的技巧，以及常見問題的解決方法。

5.1 讓指令更有效的三個技巧

1. 從簡到繁，迭代配置 ：不要一開始就勾選所有選項。先從最核心的語言和項目類型開始。讓AI助手適應基本規範後，再逐步添加“DDD原則”、“嚴格的錯誤處理”等高級要求。這可以避免指令過於複雜導致AI理解混亂。
2. 在指令中嵌入“活文檔” ：你可以在Web生成器的“Project Info”框或通過直接編輯模板，加入你項目特有的約定。例如：“本項目使用 uuid 作為所有數據表的主鍵，請勿使用自增ID。” 或者 “所有API響應必須包裹在 {code: number, data: T, message: string} 的結構中。” 這能極大提升生成代碼的可用性。
3. 結合工具的自定義指令 ：Cursor和Copilot通常也允許在聊天框或評論中編寫一次性指令。你可以將生成的核心指令（如架構規範）放在配置文件中，而將當前正在編寫的模塊的具體要求（如“請為UserService實現一個根據郵件模糊查詢並分頁的方法”）作為即時指令輸入。長效配置與短效上下文結合，效果最佳。

5.2 常見問題速查表

問題現象	可能原因	解決方案
Cursor完全無視 .cursorrules	1. 文件不在項目根目錄。 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編程夥伴，也得到了一份不斷演進的、機器可讀的項目開發規範文檔。