# 项目 AI 初始化从头开始分析项目代码库并生成代理友好的上下文文件，使所有 AI 编码工具（Claude Code、Kiro、Cursor、GitHub Copilot、Codex、OpenCode、Trae）能够快速了解项目并生成高质量的工作。 ## 执行模式技能启动时，首先选择执行模式。使用“userInput”工具呈现可点击的选项。根据时间预算和项目需求选择最合适的方案： { "question": "🚀 选择执行模式：", “选项”：[ { "title": "⚡ 快速模式（~5 分钟）", "description": "仅生成 CLAUDE.md — 让 AI 立即可用。最适合：快速试用、个人项目、时间有限" }, { "title": "📋 标准模式（~30 分钟）", "description": "生成 CLAUDE.md + 架构文档 + 技术堆栈文档 + AI 工具配置。最适合：团队项目、多工具支持", “推荐”：正确 }, { "title": "🔬 完整模式（~1-2 小时）", "description": "深入分析每个模块/页面，生成完整的文档。最适合：大型项目，需要精确的上下文" } ] } ### 模式比较 | ⚡ 快点| 📋 标准 | 🔬 满 ---|---|---|--- **预计时间** |约 5 分钟 |约 30 分钟 | 〜1-2小时 **生成的内容** |仅 CLAUDE.md | CLAUDE.md + 文档/ + AI 工具配置 |所有 + 每个模块/页面文档 **最适合** |快速试用，个人项目|团队项目，多工具支持 |大型项目，精确的背景 **深度分析** | ❌ |列出模块/页面 | ✅ 互动深度探究 **特定于工具的配置** | ❌ | ✅ | ✅ **验证阶段** | ❌ | ✅（可选）| ✅（可选） ### 模式 × 阶段执行矩阵相| ⚡ 快点| 📋 标准 | 🔬 满 ---|---|---|--- 0 模式和语言选择 | ✅ | ✅ | ✅ 1 基本信息收集| ✅ | ✅ | ✅ 1.5 资源发现| ✅ | ✅ | ✅ 2 互动探索 | ✅（精简版）| ✅ | ✅ 3 架构+API分析| ❌ | ✅ | ✅ 4 后端模块深度剖析 | ❌ | ❌（仅列出）| ✅（互动） 5 前端页面分析| ❌ | ❌（仅列出）| ✅（互动） 6 生成常用文件 | ✅（仅限 CLAUDE.md）| ✅（全部）| ✅（所有+模块/页面文档） 7 个特定于工具的配置 | ❌ | ✅ | ✅ 8 输出总结 | ✅ | ✅ | ✅ 9 验证阶段 | ❌ | ✅（可选）| ✅（可选） > 💡 **建议** ：如果用户不确定，建议📋 标准模式 - 但始终等待明确的用户确认。切勿自动选择。 ## 快速入门 1. **选择执行模式** : 根据时间预算选择⚡快速/📋标准/🔬完整 2. **选择输出语言** : 选择生成文件的语言 3. **确定项目类型** ：扫描目录结构，识别frontend/backend/fullstack/monorepo 4. **收集基本信息**：读取配置文件，提取技术堆栈 5. **确认团队工具** ：询问团队使用哪些AI工具（Claude Code / Kiro / Cursor / GitHub Copilot / Codex / OpenCode / Trae） 6. **深度分析**：按模块分析后端，按页面路由分析前端（仅标准列表，全面深入） 7. **生成通用文件**：CLAUDE.md + 模块文档 + 页面文档 + 架构文档 + 技术堆栈文档 + PR/Issue 模板（仅快速生成 CLAUDE.md） 8. **生成特定于工具的配置**：为每个 AI 工具生成专用的规则/指导/规则文件（快速跳过此部分） 9. **人工审核**：标记为 TODO 的部分需要团队输入 ## 核心原则 * 90% 的 AI 代码质量取决于它接收到的上下文 * 区别对待前端和后端：后端专注于模块职责/业务规则/状态机；前端专注于页面路由/组件树/交互流 * 共享层是全局可见的：实用方法、共享组件、API 约定进入 CLAUDE.md * 一项分析有益于所有 AI 工具（标准 Markdown，不依赖于任何特定工具） * 经过人工审核后，承诺将回购协议作为团队共享的人工智能上下文基础设施 ## 互动发现在分析之前，请确认以下内容： **项目基础知识：** * 这是一个什么样的项目？（Web 应用程序、API 服务、CLI 工具、库） * 主要语言和框架？ * 团队规模？（单人、小队、大队） **业务背景：** * 用户是谁？它解决什么问题？ * 核心业务流程是什么？ * 哪些模块/页面最复杂？ **现有约定：** * 团队有编码风格指南吗？ * 有什么API设计约定吗？ *人工智能应该知道什么“不成文的规则”？ **人工智能工具使用：** * 团队使用哪些人工智能编码工具？ * 将为每个选定的工具生成特定于工具的配置文件使用“userInput”工具来呈现带有可切换选项的工具选择： { "question": "🔧 选择您的团队使用的 AI 编码工具。将为所选工具生成配置。\n\n(当前工具已预先选择。切换您的团队需要的其他工具。)", “选项”：[ { "title": "选择要配置的工具", "subOptionsLabel": "人工智能编码工具", “子选项”：[ { "title": "克劳德代码", "description": ".claude/rules/,commands/, settings.json, .claudeignore" }, { "title": "Kiro", "description": ".kiro/steering/ 规则文件（始终加载 + 条件加载）" }, { "title": "Cursor", "description": ".cursor/rules/ 具有 glob 路径匹配的 .mdc 文件" }, { "title": "GitHub Copilot", "description": ".github/copilot-instructions.md 单文件说明" }, { "title": "Codex", "description": "AGENTS.md 说明文件（根 + 每个目录）" }, { "title": "OpenCode", "description": ".opencode/instructions.md 项目说明" }, { "title": "Trae", "description": ".trae/rules/ 带有 YAML frontmatter 的规则文件" } ] } ] } ## 配置决策树开始 — 扫描目录结构 │ ├─ 1.有packages/或apps/目录 │ └─ Monorepo → 列出子项目，用户选择，分析每个子项目（每个子项目重新运行检测） │ ├─ 2.根目录.md文件>50%，无src/或app/目录 │ └─ 文档/知识库 → 运行文档结构分析（目录层次结构+命名约定+导航文件） │ ├─ 3. 有 bin/ 目录，或者 package.json 有 bin 字段，或者 CLI 入口文件存在（cli.ts/cli.py/main.go） │ └─ CLI 工具 → 运行命令结构分析（入口点+子命令+参数定义） │ ├─ 4.有src/index.*入口+package.json有main/exports字段，没有页面目录 │ └─ 库/SDK → 运行API表面分析（公共接口+类型定义+示例代码） │ ├─ 5. 有 Dockerfile + 服务入口（例如 main.ts/app.py/main.go），无前端页面目录 │ └─ 微服务 → 运行服务接口分析（路由+健康检查+配置管理+服务间通信） │ ├─ 5.5 有 IaC 配置文件（.tf、cdk.json、Pulumi.yaml、ansible.cfg、main.bicep、Chart.yaml、CloudFormation 模板） │ └─ 基础设施 → 检测单/多项目结构，对每个项目运行 IaC 分析 │ ├─ 单个项目→直接分析（模块、工作区、资源） │ └─ 多项目 → 列出项目，独立分析每个项目，映射共享模块 │ ├─ 7.有app/或pages/页面目录，无服务/控制器层 │ └─ 仅前端 → 运行前端分析（页面路由+共享层） │ ├─ 8.有服务/控制器层，无页面目录 │ └─ 仅后端 → 运行后端分析（功能模块） │ ├─ 9.既有页面目录又有服务/控制器层 │ └─ Fullstack → 运行前端+后端分析 │ └─ 10. 以上都不匹配 └─ 通用项目→使用基本分析策略 > 💡 **优先说明** ：按数字从上到下匹配，在第一个匹配处停止。 Monorepo 具有最高优先级（递归检测子项目），文档/知识库次之（以避免错误分类）。有关非 Web 项目类型的详细分析策略，请参阅 [references/non-web-project-analysis.md]()。 ## 生成的配置 ### 通用文件（在所有工具之间共享）文件|目的|生成时 ---|---|--- **克劳德.md** |代理规则文件（包括共享层）|总是 **文档/architecture.md** |架构概述 + 模块/页面索引 |推荐 **文档/模块/{名称}.md** |后端模块业务逻辑文档 |后端/全栈项目，每个模块一个 **文档/页面/{名称}.md** |前端页面业务逻辑文档 |前端/全栈项目，每页一个 **docs/tech-stack.md** |技术堆栈和编码标准 |推荐 **.github/PULL_REQUEST_TEMPLATE.md** |公关模板|推荐 **.github/ISSUE_TEMPLATE/** |问题模板 |可选 ### AI 工具特定配置工具|生成的文件 |描述 ---|---|--- **克劳德·代码** | `.claude/rules/`、`.claude/commands/`、`.claude/settings.json`、`.claudeignore` |路径级规则+斜杠命令+权限配置+文件忽略规则 **基罗** | `.kiro/steering/product.md`、`tech.md`、`struction.md`、`conventions.md`、`api.md`、`frontend.md` |引导规则文件，支持始终加载和条件加载 **光标** | `.cursor/rules/project.mdc`、`frontend.mdc`、`backend.mdc`、`testing.mdc` |具有 glob 路径匹配的 .mdc 规则文件 **GitHub 副驾驶** | `.github/copilot-instructions.md` |单文件全局指令（精简） **法典** | `AGENTS.md`（根），每个目录`AGENTS.md` | OpenAI Codex指令文件，支持分层继承，子目录规则覆盖根规则 **开放代码** | `.opencode/instructions.md` |项目级指令文件，纯Markdown格式 **特雷** | `.trae/rules/project.md`、`frontend.md`、`backend.md` |使用 YAML frontmatter 控制负载条件的规则文件请参阅 [references/tool-specific-configs.md]()。 ## 工作流程 ### 第 0 阶段：模式和语言选择（强制，切勿跳过） > ⛔ **强制交互** ：在任何情况下，您都必须呈现以下选项并等待用户明确回复才能继续。切勿自动选择默认模式。永远不要根据项目特点为用户做决定。使用“userInput”工具呈现可点击模式选项： { "question": "🚀 选择执行模式：", “选项”：[ { "title": "⚡ 快速模式（~5 分钟）", "description": "仅生成 CLAUDE.md — 让 AI 立即可用。最适合：快速试用、个人项目、时间有限" }, { "title": "📋 标准模式（~30 分钟）", "description": "生成 CLAUDE.md + 架构文档 + 技术堆栈文档 + AI 工具配置。最适合：团队项目、多工具支持", “推荐”：正确 }, { "title": "🔬 完整模式（~1-2 小时）", "description": "深入分析每个模块/页面，生成完整的文档。最适合：大型项目，需要精确的上下文" } ] } 用户选择一个选项后，记录模式选择。然后使用“userInput”工具呈现可点击的语言选项： { "question": "🌐 选择生成文件的输出语言:", “选项”：[ { "title": "英文", "description": "生成所有英文输出文件" }, { "title": "中文（中文）", "description": "生成所有中文输出文件" }, { "title": "日本语（日语）", "description": "生成所有日语输出文件" }, { "title": "自动检测", "description": "遵循项目的主要语言" } ] } > 💡 此语言选择仅影响生成的输出文件（CLAUDE.md、docs/、steering 等）。技能说明本身仍为英文。 **用户确认两个选择后，进入第 1 阶段。** ### 第一阶段：基本信息收集⚡📋🔬 读取项目配置文件并提取技术堆栈信息：文件|提取信息 ---|--- `package.json` |项目名称、脚本、依赖、框架检测 `pyproject.toml` / `requirements.txt` | Python 依赖项 `go.mod` / `Cargo.toml` | Go/Rust 依赖项 `tsconfig.json` | TypeScript 配置 `.eslintrc*` / `.prettierrc*` |代码风格规则 `自述文件.md` |项目描述、业务背景 `.env.example` |环境变量列表（仅读取名称，从不读取值） ### 阶段 1.5：资源发现⚡📋🔬 在生成任何文件之前，请检查目标项目中是否已存在 AI 配置文件。根据检测结果，用户可以选择增量更新、跳过现有文件或重新生成所有内容。 > 此阶段在所有模式下运行（⚡快速/📋标准/🔬完整）。 #### 1\.检查现有的配置文件扫描目标工程中是否已存在以下文件/目录：路径|类型 |描述 ---|---|--- `克劳德.md` |文件|通用代理规则文件 `.claude/rules/` |目录 | Claude Code 路径级规则 `.claude/命令/` |目录 |克劳德代码斜线命令 `.claude/settings.json` |文件|克劳德代码权限配置 `.claudeignore` |文件|克劳德代码忽略文件 `.kiro/转向/` |目录 | Kiro 转向规则文件 `.cursor/rules/` |目录 |游标规则文件 `.github/copilot-instructions.md` |文件| GitHub Copilot 全局说明 `代理.md` |文件|食品法典根级说明 `.opencode/instructions.md` |文件| OpenCode 项目说明 `.trae/rules/` |目录 | Trae规则文件 `docs/architecture.md` |文件|架构文档 `文档/模块/` |目录 |后端模块文档 `文档/页面/` |目录 |前端页面文档 `docs/tech-stack.md` |文件|技术堆栈文档对于已有文件，读取内容并记录文件大小（字数）；对于现有目录，记录文件计数和文件名列表。 #### 2\.目前的发现结果向用户显示找到的内容： 🔍 检测到现有的AI配置： ✅ CLAUDE.md（1,234 字） ✅ .kiro/steering/（4 个文件：product.md、tech.md、struction.md、conventions.md） ✅ docs/architecture.md（856字） ❌.claude/rules/（未找到） ❌.claude/commands/（未找到） ❌.claude/settings.json（未找到） ❌ .claudeignore（未找到） ❌ .cursor/rules/（未找到） ❌ .github/copilot-instructions.md（未找到） ❌ AGENTS.md（未找到） ❌.opencode/instructions.md（未找到） ❌.trae/rules/（未找到） ❌ docs/modules/（未找到） ❌ 文档/页面/（未找到） ❌ docs/tech-stack.md（未找到） > 如果根本不存在配置文件，则跳过用户选择步骤并直接进入阶段 2。 #### 3\.用户选择处理策略当检测到现有配置文件时，询问用户：选择处理策略： 1️⃣ 增量更新 - 将新分析合并到现有文件中 ✅ 保留手动编辑的内容 ✅ 添加缺失的部分 ✅ 更新过时的信息（例如依赖版本） ⚠️ 需要对合并结果进行人工审核 2️⃣ Skip Existing — 只生成不存在的文件（默认） ✅ 不修改任何现有文件 ✅ 最安全的选择 ⚠️现有文件可能缺少新分析的信息 3️⃣ 全部重新生成 — 备份现有文件，然后从头开始重新生成 ✅ 获取最新、最完整的配置 ⚠️ 覆盖手动编辑的内容（现有文件备份到 .ai-init-backup/） **每个选项的执行逻辑：** * **增量更新** ：对现有文件执行节级合并（保留用户编辑、添加缺失的节、更新过时的信息）；正常生成丢失文件 * **跳过现有** ：保持当前行为 - 不触及现有文件，仅生成丢失的文件 * **重新生成全部** ：将现有文件备份到 `.ai-init-backup/{timestamp}/`，然后从头开始生成所有内容 > 💡 用户还可以针对不同的文件选择不同的策略（例如“增量更新CLAUDE.md，重新生成其余的”）。有关详细的合并规则、冲突处理和备份策略，请参阅 [references/incremental-update-strategy.md]()。 ### 第二阶段：目录结构分析+项目类型检测⚡📋🔬 扫描根目录和一级子目录，识别架构模式并确定项目类型。 > ⚡ **快速模式** ：使用精简交互，减少确认问题，快速确定项目类型。请参阅 [references/directory-patterns.md]()。 ### 第 3 阶段：代码风格采样📋🔬 > ⚡ **快速模式会跳过此阶段。** 从主要语言中随机读取 3-5 个源文件（不包括测试和配置）以推断编码约定。请参阅 [references/code-style-sampling.md]()。 ### 第 4 阶段：后端模块深度分析🔬（仅限后端/全栈项目） > ⚡ **快速模式跳过此阶段。** 📋 **标准模式**：仅列出模块名称，无需深入探讨。 🔬 **完整模式**：交互式每个模块深度分析。 1.从service/controller/model目录推断业务模块列表 2. 向用户呈现模块列表，询问要深入分析哪些模块（完整模式） 3.读取每个模块的核心文件，提取业务规则、状态机、流程、依赖项（完整模式） 4.将复杂模块（服务> 800行或3个以上子域）拆分为多个文档（完整模式）请参阅 [references/backend-analysis.md]()。 > 🏗️ **基础设施项目**：第 4 阶段被特定于 IaC 的分析所取代：单/多项目检测 → 每个项目模块解析 → 工作区检测 → 资源库存提取 → 可选的云 CLI 查询。请参阅 [infrastruction-analysis.md]()。 ### 第 5 阶段：前端页面路由和组件分析🔬（仅限前端/全栈项目） > ⚡ **快速模式跳过此阶段。** 📋 **标准模式**：仅列出页面路由，无需深入研究。 🔬 **完整模式**：交互式每页深度分析。 1.从路由目录推断页面路由树 2. 向用户呈现页面列表，询问要深入分析哪些页面（完整模式） 3.读取每页的入口文件和子组件，提取组件树、状态管理、交互流程（Full模式） 4. 扫描共享层：UI组件、业务组件、实用方法、API层、全局状态（Full模式） 5.将复杂页面（5+个独立功能区）拆分为多个文档（完整模式）请参阅 [references/frontend-analysis.md]()。 ### 第 6 阶段：生成上下文文件 ⚡📋🔬 > ⚡ **快速模式** ：仅生成 CLAUDE.md，跳过 docs/、PR/Issue 模板等。 📋 **标准模式** ：生成 CLAUDE.md + docs/ + PR/Issue 模板。 🔬 **完整模式**：生成所有内容，包括每个模块/每个页面的详细文档。 > 🌐 **Language** ：以用户在阶段 0 选择的语言生成所有输出内容。 #### 1\. CLAUDE.md（始终生成）包含：技术堆栈、项目结构、命令、代码约定、架构决策、重要上下文（模块/页面概述 + 关键业务规则）、通用实用程序和共享组件、API 层约定、请勿操作、环境变量。请参阅 [assets/CLAUDE.md.template]()。 #### 2\.文档/architecture.md（推荐）包含：系统架构图、后端模块索引、前端页面索引、数据流、数据库架构、API结构、外部服务。请参阅[assets/architecture.md.template]()。 #### 3\. docs/modules/{name}.md（后端模块文档）每个后端模块一个文档，包含：职责、核心文件、实体、状态机、业务规则、流程、依赖项、第三方集成、错误处理、常见陷阱。请参阅[assets/module.md.template]()。 #### 4\. docs/pages/{name}.md（前端页面文档）每个前端页面一个文档，包含：职责、路由、组件树、状态管理、数据获取、交互流程、共享组件依赖项、常见陷阱。请参阅 [assets/page.md.template]()。 #### 5\. docs/tech-stack.md（推荐）请参阅 [assets/tech-stack.md.template]()。 #### 6\。 PR/问题模板（推荐）请参阅 [assets/pr-template.md]() 和 [assets/issue-templates/]()。 ### 第 7 阶段：生成特定于 AI 工具的配置📋🔬 > ⚡ **快速模式会跳过此阶段。** > ⛔ **强制交互** ：在生成任何特定于工具的配置之前，您必须呈现下面的工具选择界面并等待用户的明确确认。切勿跳过此步骤。切勿自动选择所有工具。 **第1步：检测当前运行环境。** 识别当前是哪个AI编码工具正在执行该技能（例如，如果在Kiro内部运行，则当前工具为“Kiro”；如果在Cursor内部运行，则当前工具为“Cursor”）。默认情况下，仅应预先选择检测到的当前工具。 **第 2 步：显示工具选择。** 使用具有以下参数的“userInput”工具： { "question": "🔧 选择您的团队使用的 AI 编码工具。将为所选工具生成配置。\n\n(当前工具已预先选择。切换您的团队需要的其他工具。)", “选项”：[ { "title": "选择要配置的工具", "subOptionsLabel": "人工智能编码工具", “子选项”：[ { "title": "克劳德代码", "description": ".claude/rules/,commands/, settings.json, .claudeignore" }, { "title": "Kiro", "description": ".kiro/steering/ 规则文件（始终加载 + 条件加载）" }, { "title": "Cursor", "description": ".cursor/rules/ 具有 glob 路径匹配的 .mdc 文件" }, { "title": "GitHub Copilot", "description": ".github/copilot-instructions.md 单文件说明" }, { "title": "Codex", "description": "AGENTS.md 说明文件（根 + 每个目录）" }, { "title": "OpenCode", "description": ".opencode/instructions.md 项目说明" }, { "title": "Trae", "description": ".trae/rules/ 带有 YAML frontmatter 的规则文件" } ] } ] } **第 3 步：处理用户选择。** * 解析用户的响应以确定选择了哪些工具。 * **如果未选择任何工具** ：提示用户在继续之前必须至少选择一种工具。重新呈现工具选择界面。 * **如果选择了一个或多个工具**：记录所选工具列表并继续仅为所选工具生成配置。 **第4步：生成配置。** 根据确认的选择，从CLAUDE.md和分析结果中拆分并生成特定于工具的配置文件。仅为用户选择的工具生成配置 - 跳过所有未选择的工具。 > 🌐 **语言** ：以用户在第 0 阶段选择的语言生成所有特定于工具的配置内容。 #### 克劳德代码（如果团队使用它）生成完整的 Claude Code 配置系统，包括路径级规则、斜杠命令、权限配置和文件忽略规则。 ##### 1\. `.claude/rules/` — 路径级规则从 CLAUDE.md 中拆分出来，生成路径级规则文件： * `frontend.md` — 前端组件、共享组件、状态管理规则 * `backend.md` — 后端 API、错误处理、数据库规则 * `testing.md` — 测试组织、命名、模式规则请参阅 [assets/claude-rules/]()。 ##### 2\. `.claude/commands/` — 斜杠命令生成克劳德代码斜线命令。每个“.md”文件都会自动注册为“/command-name”命令。 **生成步骤：** 1. 复制 `assets/claude-commands/commit.md.template` → `.claude/commands/commit.md` 2. 复制 `assets/claude-commands/review.md.template` → `.claude/commands/review.md` 3. 定制： * 读取`package.json`脚本，将常用脚本命令集成到提交/审核工作流程中 * Monorepo 项目：将范围建议列表（子包名称）添加到 commit.md * 如果项目有特定的提交约定（例如 JIRA 票证前缀），请添加到 commit.md 约定部分 4.建议用户根据需要添加自定义命令（例如`deploy.md`、`migrate.md`） **生成的文件：** * `commit.md` — Git 提交工作流程（分析 `git diff --staged` → 生成常规提交消息 → 执行提交） * `review.md` — 代码审查工作流程（代码质量→安全性→性能→测试覆盖率→项目约定，按🔴🟡🟢严重性输出）请参阅 [assets/claude-commands/]()。 ##### 3\. `.claude/settings.json` — 权限配置生成克劳德代码权限配置，控制人工智能可以做什么和不能做什么。 **生成步骤：** 1.从`assets/claude-settings.json.template`开始 2.检测包管理器(npm/pnpm/yarn/bun)，替换命令前缀 3. 读取 `package.json` 脚本，将项目定义的脚本添加到 `allow` 列表中 4.检测项目工具链（Docker → `docker compose *`、Prisma → `npx prisma *`、Python → `python *`） 5. 安全审核：确保“拒绝”列表中的危险命令（“rm -rf”、“npmpublish”、“git push --force”、“curl|bash”、“sudo”）不会出现在“允许”列表中 6. 输出最终`.claude/settings.json` 请参阅 [assets/claude-settings.json.template]()。 ##### 4\. `.claudeignore` — 文件忽略规则在项目根目录中生成“.claudeignore”（与“.gitignore”一起），以防止 AI 访问敏感信息或在不相关的文件上浪费上下文。 **生成步骤（三层叠加）：** 1. **第 1 层 — .gitignore base** ：读取项目的 `.gitignore` （如果存在），重用其忽略规则 2. **第 2 层 — AI 工具默认忽略模式**：从 `assets/claudeignore.template` 加载（环境变量、密钥/证书、大型二进制文件、构建工件、本地数据库等） 3. **第 3 层 - 项目特定的敏感文件**：通过 `scan_project.py` 检测（`.env*`、`*.pem`、`*.key`、包含机密/凭证的文件名等） 4. 合并和去重，确保`.env.example`不被忽略（添加`!.env.example`否定规则） 5. 检测大型资源目录（例如`public/images/`、`static/assets/`），如果较大建议忽略 6. 输出带有分类注释的`.claudeignore` > ⚠️ 如果 `.claudeignore` 已经存在，则跳过生成并通知用户。请参阅 [assets/claudeignore.template]()。有关详细的格式规范，请参阅 [references/tool-specific-configs.md]()。 #### Kiro（如果团队使用它）生成带有转向文件的`.kiro/steering/`目录，支持始终加载和条件加载： * `product.md` — 产品概述、业务模块摘要、关键业务规则（始终加载） * `tech.md` — 技术堆栈、命令、关键依赖项（始终加载） * `struction.md` — 项目结构、架构决策、模块/页面索引（始终加载） * `conventions.md` — 编码约定，不规则（始终加载） * `api.md` — API 约定（条件加载：匹配 API 相关文件） * `frontend.md` — 共享组件、实用方法、前端约定（条件加载：匹配前端文件）指导文件通过“#[[file:docs/modules/xxx.md]]”引用详细文档，保持轻量级。请参阅 [assets/kiro-steering/]()。 #### 光标（如果团队使用它）生成 `.cursor/rules/` 目录，其中包含支持 glob 路径匹配的 .mdc 规则文件： * `project.mdc` — 全局规则（alwaysApply：true） * `frontend.mdc` — 前端规则（glob 匹配 `**/*.tsx` 等） * `backend.mdc` — 后端规则（glob 匹配 `**/services/**` 等） * `testing.mdc` — 测试规则（glob 匹配 `**/*.test.*` 等）请参阅 [assets/cursor-rules/]()。 #### GitHub Copilot（如果团队使用它）生成 `.github/copilot-instructions.md` 单文件全局指令，由 CLAUDE.md 压缩而成（Copilot 的上下文窗口较小，内容必须简洁）。请参阅 [assets/copilot-instructions.md.template]()。 #### Codex（如果团队使用它）从 CLAUDE.md 分析结果生成 Codex 指令文件。 ##### 1\. `AGENTS.md` — 根级指令创建根级 `AGENTS.md` 文件，其中包含： * 项目概述和技术堆栈总结 * 全球编码约定和标准 * 架构指南 * 关键约束和禁止模式 ##### 2\.每个目录“AGENTS.md”（可选）如果项目具有不同的模块（例如“src/”、“tests/”、“docs/”），则生成子目录级“AGENTS.md”文件： * `src/AGENTS.md` — 源代码约定、导入规则、组件模式 * `tests/AGENTS.md` — 测试约定、框架使用、覆盖率要求 **层次结构规则**：子目录 AGENTS.md 规则覆盖/补充根级别规则。让子目录文件专注于特定于目录的问题。 #### OpenCode（如果团队使用它）从 CLAUDE.md 分析结果生成 OpenCode 项目指令。 ##### 1\. `.opencode/instructions.md` — 项目说明创建一个项目说明文件，其中包含： * 项目概况及目的 * 技术堆栈和关键依赖项 * 编码约定和标准 * 架构模式和指南 * 禁止的模式和常见的陷阱 **格式**：纯Markdown，单个文件。保持简洁并专注于可操作的指示。 #### Trae（如果球队使用它）从 CLAUDE.md 分析结果生成 Trae 规则文件。 ##### 1\. `.trae/rules/project.md` — 全局规则使用 YAML frontmatter 创建全局规则文件： --- 描述：“项目范围的编码标准和约定” 全局：“**/*” 总是应用：正确 --- 内容：项目概述、技术堆栈、全球编码约定、架构指南。 ##### 2\. `.trae/rules/frontend.md` — 前端规则（如果适用） --- 描述：《前端开发规则》全局：“src /组件/ **，src /页面/ **，src /应用程序/ **” 总是应用：假 --- 内容：组件模式、状态管理、样式约定、可访问性规则。 ##### 3\. `.trae/rules/backend.md` — 后端规则（如果适用） --- 描述：《后端开发规则》全局：“src/api/**，src/server/**，src/services/**” 总是应用：假 --- 内容：API 模式、数据库约定、错误处理、安全规则。 **格式** ：带有 YAML frontmatter 的 Markdown。支持条件加载的 glob 路径匹配（类似于 Cursor 的 .mdc 格式）。 ### 第 8 阶段：输出总结和审查 ⚡📋🔬 输出生成的文件列表、技术堆栈摘要、模块/页面计数、需要人工输入的 TODO 列表。 ### 第 9 阶段：验证阶段📋🔬（可选） > ⚡ **快速模式跳过此阶段。** 📋🔬 **标准和完整模式可选执行**，默认为跳过。在第 8 阶段输出摘要之后，可选择运行验证，让 AI 尝试执行一个简单的任务来验证生成的配置是否有效。 #### 1\.询问用户是否验证运行配置验证？人工智能将尝试执行一项简单的任务来验证生成的配置是否有效。（是/跳过）默认：跳过 > 如果用户选择跳过或按 Enter 键，则跳过阶段 9 并完成。 #### 2\.选择验证方法选择验证方法： 1️⃣ 脚本验证 — 运行 validate_output.py 检查文件完整性检查 CLAUDE.md 所需部分、TODO 标记、Markdown 链接有效性 2️⃣ AI 任务验证 — 让 AI 尝试一个简单的代码任务在分析的模块/页面中添加一个简单的函数，验证 AI 正确引用文档并遵循约定 3️⃣ 两者都运行 #### 3\.执行验证 **脚本验证（选项 1️⃣ 或 3️⃣）：** 运行输出验证脚本： python 脚本/validate_output.py 该脚本检查：CLAUDE.md 是否存在和必需的部分、TODO 标记计数、Markdown 内部链接有效性、docs/ 目录结构完整性。 **人工智能任务验证（选项 2️⃣ 或 3️⃣）：** 1. 选择一个分析的模块/页面作为验证目标 2. AI尝试简单的代码任务（例如，向服务添加实用功能，向页面添加帮助组件） 3.任务完成后，检查AI是否： * ✅ 从相关模块/页面文档正确引用业务规则 * ✅ 遵循 CLAUDE.md 代码约定中的编码约定 * ✅ 遵守 CLAUDE.md 的禁令请勿 * ✅ 使用通用实用程序中记录的共享实用程序/组件 #### 4\.输出结果及改进建议按通过/警告/失败总结验证结果： 📋验证结果： ✅ AI 正确引用了模块文档中的业务规则 ✅ AI 遵循代码约定中的命名约定 ⚠️ AI 没有引用 Common Utilities 中的实用方法 ❌ AI 违反了“请勿”的禁令建议的改进： - 在 CLAUDE.md 常用实用程序部分添加实用程序方法的使用示例 - 在“禁止”部分添加更具体的禁止场景 **如果验证显示配置差距：** * 指出哪些配置文件和部分需要改进 * 给出具体的改进建议 * 如果问题严重，建议人工审核 **如果所有验证均通过：** 🎉 验证通过！人工智能可以正确理解项目上下文并遵循编码约定。生成的配置文件已准备好提交到存储库。 ## 输出结构 Fullstack项目（团队使用Claude Code + Kiro + Cursor + Codex）：项目/ ├── CLAUDE.md ← 通用代理规则文件 ├── AGENTS.md ← Codex 根级指令 ├── 文档/ │ ├── Architecture.md ← 架构概述+索引 │ ├── tech-stack.md ← 技术栈文档 │ ├── 模块/ ← 后端模块文档 │ │ ├── auth.md │ │ ├── 课程.md │ │ └── payment-core.md │ └── 页面/ ← 前端页面文档 │ ├── home.md │ ├── 课程详情.md │ └── 仪表板.md ├── .claude/ ← Claude 代码特定 │ ├── settings.json ← 权限配置（允许/拒绝） │ ├── 规则/ │ │ ├── 前端.md │ │ ├── 后端.md │ │ └── 测试.md │ └── 命令/ │ ├── commit.md ← /commit 斜杠命令 │ └── review.md ← /review 斜杠命令 ├── .claudeignore ← Claude 代码文件忽略规则（与 .gitignore 一起） ├── .kiro/ ← Kiro 特定 │ └── 转向/ │ ├── 产品.md │ ├── 技术.md │ ├── 结构.md │ ├── 约定.md │ ├── api.md ← 条件加载 │ └── frontend.md ← 条件加载 ├── .cursor/ ← 光标特定 │ └── 规则/ │ ├── 项目.mdc ← 总是应用 │ ├── frontend.mdc ← 全局匹配 │ ├── backend.mdc ← 全局匹配 │ └── testing.mdc ← 全局匹配 ├── .opencode/ ← OpenCode 特定（如果使用） │ └── instructions.md ← 项目级指令 ├── .trae/ ← Trae 特定（如果使用） │ └── 规则/ │ ├── project.md ← 全局规则(alwaysApply) │ ├── frontend.md ← 前端规则（全局匹配） │ └── backend.md ← 后端规则（全局匹配） └── .github/ ├── copilot-instructions.md ← 副驾驶特定（如果使用） ├── PULL_REQUEST_TEMPLATE.md └── 问题模板/ 注意：仅为团队实际使用的工具生成特定于工具的配置。 ## 安全规则 1. **只读分析，永不修改代码** — 只生成新文件，永不修改现有项目代码 2. **永远不要读取敏感数据** - `.env` 仅读取变量名称，从不读取值；从不读取关键文件 3. **标记不确定的部分** — 无法推断的信息标记为“TODO：请填写”，切勿猜测 4. **永不覆盖现有文件** — 如果目标文件存在，则跳过并通知用户 5. **通用格式**——生成标准Markdown，不依赖于任何特定AI工具的专有格式 ## 参考资料参考|何时阅读 ---|--- [directory-patterns.md]() |目录结构识别&项目类型检测 [non-web-project-analysis.md]() |非 Web 项目（文档/知识库、CLI 工具、库/SDK、微服务）分析策略 [code-style-sampling.md]() |代码风格采样策略 [backend-analysis.md]() |后端模块深度分析方法 [frontend-analysis.md]() |前端页面路由&组件分析方法 [工具特定-configs.md]() | AI工具特定配置文件生成指南 [incremental-update-strategy.md]() |阶段1.5资源发现：增量更新策略、合并规则、冲突处理、备份策略 [基础设施分析.md]() |基础设施/IaC项目分析：多项目检测、工作空间分析、云CLI资源查询 ## 模板 ### 常用模板模板|目的 ---|--- [CLAUDE.md.template]() |代理规则文件模板 [architecture.md.template]() |架构文档模板 [module.md.template]() |后端模块文档模板 [page.md.template]() |前端页面文档模板 [tech-stack.md.template]() |技术堆栈文档模板 [pr-template.md]() |公关模板 [问题模板/]() |问题模板 [infrastruct.md.template]() |基础设施/IaC 项目文档模板 ### AI 工具特定模板模板|工具|目的 ---|---|--- [claude-rules/]() |克劳德·代码 | `.claude/rules/` 路径级规则模板 [claude-commands/]() |克劳德·代码 | `.claude/commands/` 斜杠命令模板（commit.md、review.md） [claude-settings.json.template]() |克劳德·代码 | `.claude/settings.json` 权限配置模板 [claudeignore.template]() |克劳德·代码 | `.claudeignore` 文件忽略规则模板 [kiro-steering/]() |基罗 | `.kiro/steering/` 转向文件模板 [cursor-rules/]() |光标| `.cursor/rules/` .mdc 规则模板 [copilot-instructions.md.template]() | GitHub 副驾驶 |全局指令模板 ## 支持的项目类型项目类型 |检测标准|分析策略|支持级别|参考 ---|---|---|---|--- Next.js / React 全栈 |既有页面目录又有服务/控制器层 |同时分析前端+后端 | ⭐⭐⭐⭐⭐ | [frontend-analysis.md](), [backend-analysis.md]() 仅前端（Vite/CRA/Vue）|有 `app/` 或 `pages/` 页面目录，没有服务/控制器层 |页面路由+共享层| ⭐⭐⭐⭐⭐ | [frontend-analysis.md]() Node.js 后端 (Express/Fastify/NestJS) |有服务/控制器层，无页面目录 |模块分析| ⭐⭐⭐⭐⭐ | [backend-analysis.md]() Python（Django/FastAPI/Flask）|有服务/控制器层，无页面目录 |后端分析 | ⭐⭐⭐⭐ | [backend-analysis.md]() 去 / Rust |有服务/控制器层，无页面目录 |基础后端分析 | ⭐⭐⭐ | [backend-analysis.md]() 莫诺雷波 |具有 `packages/` 或 `apps/` 目录 |每个子项目分析 | ⭐⭐⭐⭐ | [目录模式.md]() 反应本机 |有 `screens/` 目录 + React Native 依赖项 |通过屏幕分析 | ⭐⭐⭐⭐ | [frontend-analysis.md]() 文档/知识库 |根 `.md` 文件 > 50%，没有 `src/`/`app/` 目录 |文档结构分析（目录层次+命名约定+导航文件+内容格式）| ⭐⭐⭐⭐ | [non-web-project-analysis.md]() CLI 工具 |具有 `bin/` 目录或 `package.json` 具有 `bin` 字段或存在 CLI 入口文件 |命令结构分析（条目+子命令+参数+输出格式）| ⭐⭐⭐⭐ | [non-web-project-analysis.md]() 库/SDK |有 `src/index.*` 条目 + `package.json` 有 `main`/`exports`，没有页面目录 | API面分析（公共接口+类型定义+版本兼容性+发布流程）| ⭐⭐⭐⭐ | [non-web-project-analysis.md]() 微服务|有 `Dockerfile` \+ 服务入口，无前端页面目录 |服务接口分析（路由+健康检查+配置管理+服务间通信）| ⭐⭐⭐⭐ | [non-web-project-analysis.md]() 基础设施/IaC |具有“.tf”文件、“cdk.json”、“Pulumi.yaml”、“ansible.cfg”、“main.bicep”、“Chart.yaml”或 CloudFormation 模板 |单/多项目结构检测→每个项目的IaC分析（模块、工作区、资源、云CLI查询）| ⭐⭐⭐⭐ | [基础设施分析.md](), [non-web-project-analysis.md]()

代码库上下文

包含技能