├── .cursorindexingignore ├── .github └── workflows │ └── claudecode.yml ├── .gitignore ├── CHANGELOG.md ├── LICENSE ├── README.md ├── docs ├── 01-核心概念和导航.md ├── 02-斜杠命令和集成系统.md ├── 03-开发工作流和最佳实践.md ├── 04-Meta-Todo智能任务系统.md ├── 05-高级协同实现.md ├── 06-快速参考和核心概念.md ├── CONTEXT-tier2-component.md ├── CONTEXT-tier3-feature.md ├── Guide.md ├── README-中文课程指南.md ├── README.md ├── ai-context │ ├── deployment-infrastructure.md │ ├── docs-overview.md │ ├── handoff.md │ ├── project-structure.md │ └── system-integration.md ├── open-issues │ └── example-api-performance-issue.md └── specs │ ├── example-api-integration-spec.md │ └── example-feature-specification.md ├── examples ├── README.md └── python-project │ └── README.md ├── install.sh ├── setup.sh └── templates ├── .claude ├── agents │ ├── OVERVIEW.md │ ├── README.md │ ├── chinese-localization-expert.md │ ├── claude-config-expert.md │ ├── mcp-integration-expert.md │ ├── shell-scripting-expert.md │ └── template-management-expert.md ├── commands │ ├── README.md │ ├── code-review.md │ ├── create-docs.md │ ├── full-context.md │ ├── gemini-consult.md │ ├── handoff.md │ ├── mcp-status.md │ ├── refactor.md │ └── update-docs.md └── hooks │ ├── README.md │ ├── config │ └── sensitive-patterns.json │ ├── gemini-context-injector.sh │ ├── mcp-security-scan.sh │ ├── notify.sh │ ├── setup │ ├── hook-setup.md │ └── settings.json.template │ ├── sounds │ ├── complete.wav │ └── input-needed.wav │ └── subagent-context-injector.sh ├── CLAUDE.md ├── MCP-ASSISTANT-RULES.md └── docs ├── CONTEXT-tier2-component.md ├── CONTEXT-tier3-feature.md ├── README.md └── ai-context ├── deployment-infrastructure.md ├── docs-overview.md ├── handoff.md ├── project-structure.md └── system-integration.md /.cursorindexingignore: -------------------------------------------------------------------------------- 1 | 2 | # Don't index SpecStory auto-save files, but allow explicit context inclusion via @ references 3 | .specstory/** 4 | -------------------------------------------------------------------------------- /.github/workflows/claudecode.yml: -------------------------------------------------------------------------------- 1 | name: Claude Code 2 | 3 | on: 4 | issue_comment: 5 | types: [created] 6 | pull_request_review_comment: 7 | types: [created] 8 | issues: 9 | types: [opened, assigned] 10 | pull_request_review: 11 | types: [submitted] 12 | 13 | jobs: 14 | claude: 15 | if: | 16 | (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) || 17 | (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) || 18 | (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) || 19 | (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude'))) 20 | runs-on: ubuntu-latest 21 | permissions: 22 | contents: read 23 | pull-requests: read 24 | issues: read 25 | id-token: write 26 | steps: 27 | - name: Checkout repository 28 | uses: actions/checkout@v4 29 | with: 30 | fetch-depth: 1 31 | - name: Setup Node.js 32 | uses: actions/setup-node@v4 33 | with: 34 | node-version: '18' 35 | - name: Install @cloudbase/cli 36 | run: npm install -g @cloudbase/cli 37 | - name: Run Claude Code 38 | id: claude 39 | uses: anthropics/claude-code-action@beta 40 | env: 41 | ANTHROPIC_BASE_URL: "${{ secrets.ANTHROPIC_BASE_URL }}" 42 | with: 43 | claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} 44 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # 开发配置文件（不提交到仓库） 2 | CLAUDE.md 3 | /.claude/ 4 | .specstory/ 5 | 6 | # 系统和临时文件 7 | *.log 8 | .DS_Store 9 | node_modules/ 10 | .env 11 | .env.local 12 | -------------------------------------------------------------------------------- /CHANGELOG.md: -------------------------------------------------------------------------------- 1 | # 更新日志 2 | 3 | 所有值得注意的项目更改将记录在此文件中。 4 | 5 | 格式基于[保持更新日志](https://keepachangelog.com/zh-CN/1.0.0/)， 6 | 本项目遵循[语义化版本](https://semver.org/lang/zh-CN/)。 7 | 8 | ## [1.2.7] - 2025-10-10 9 | 10 | ### 📝 文档更新 11 | - **移除 AnyRouter 推介** - 清理 README.md 中的第三方服务推介内容 12 | - **更新 BigModel 推介地址** - 修正智谱AI的注册链接为新的推广地址 13 | 14 | ### 🔗 链接优化 15 | - **简化推介内容** - 移除不必要的赞助商信息，聚焦核心功能 16 | - **推广链接更新** - BigModel 注册地址更新为标准推广格式 17 | 18 | ## [1.2.6] - 2025-09-13 19 | 20 | ### 🔧 文件提交修复 21 | - **修复 .gitignore 规则** - 将 `.claude/` 改为 `/.claude/`，只忽略根目录的配置文件 22 | - **添加缺失的 mcp-status.md** - 补充提交 `/mcp-status` 命令模板文件 23 | 24 | ### 📋 技术说明 25 | - 之前 `.gitignore` 中的 `.claude/` 规则意外忽略了 `templates/.claude/` 目录 26 | - 导致 `mcp-status.md` 等模板文件未被提交到远程仓库 27 | - 现在修正为只忽略项目根目录的 `.claude/` 用户配置目录 28 | 29 | ## [1.2.5] - 2025-09-13 30 | 31 | ### 🔧 重要修复 32 | - **setup.sh 默认配置优化** - 移除用户询问，默认安装所有 MCP 服务器 33 | - **MCP 服务器配置修正** - 使用正确的 `gemini-mcp-tool` 包名和服务名 34 | - **恢复 MCP 服务器配置生成** - setup.sh 现在正确生成 `settings.local.json` 中的 MCP 配置 35 | 36 | ### 📝 文档纠正 37 | - **README.md 命令列表修正** - 移除虚假的命令，替换为实际存在的斜杠命令 38 | - **命令描述准确化** - 明确说明是在 Claude Code 中使用的斜杠命令，不是终端命令 39 | 40 | ### 🛠️ 安装体验改进 41 | - **简化安装流程** - 不再询问用户选择，直接安装所有功能 42 | - **MCP 配置一致性** - 确保配置文件与实际包名保持一致 43 | 44 | ### ⚡ 技术优化 45 | - **配置生成逻辑优化** - 简化脚本逻辑，提高安装成功率 46 | - **服务器命名规范** - 统一使用正确的 MCP 扩展名称 47 | 48 | ## [1.2.4] - 2025-09-12 49 | 50 | ### 🔧 问题修复 51 | - **修复 MCP 安装命令语法** - 更新安装脚本中的 MCP 命令为正确语法 52 | - **Gemini MCP 仓库修复** - 修正 Gemini MCP 仓库 URL 和安装命令 53 | 54 | ### ✨ 新增功能 55 | - **技术专家代理系统** - 新增 5 个专业技术专家代理，提升专业咨询能力 56 | - **智浦 AI 引擎支持** - 添加智浦 AI 引擎介绍到 README 57 | - **核心命令汉化** - 完全汉化 templates/.claude/commands/ 目录下的核心 Markdown 文件 58 | 59 | ### 📝 文档改进 60 | - **中文化增强** - 提升命令文档的中文本土化体验 61 | - **AI 引擎扩展** - 丰富 AI 引擎选择和说明 62 | 63 | ### 🛠️ 技术优化 64 | - **安装流程改进** - 优化 MCP 服务器安装的稳定性和准确性 65 | - **代理系统架构** - 建立更完善的专家代理分工体系 66 | 67 | ## [1.2.3] - 2025-08-30 68 | 69 | ### 🔧 问题修复 70 | - **修复 MCP 服务器包名错误** - Context7 使用正确包名 @upstash/context7-mcp 71 | - **替换无效 Gemini MCP 服务器** - 使用可用的 gemini-mcp 包 72 | - **添加 API 密钥配置支持** - MCP 服务器配置中包含 API 密钥占位符 73 | 74 | ### 📝 用户体验改进 75 | - **完善配置提醒信息** - 安装后明确提示用户需要配置 API 密钥 76 | - **详细配置指导** - 提供具体的配置文件编辑说明 77 | 78 | ### 🔒 配置优化 79 | - **API 密钥占位符** - 设置明确的占位符提醒用户配置真实密钥 80 | - **配置文件结构修正** - 确保 MCP 服务器配置格式正确 81 | 82 | ## [1.2.2] - 2025-08-29 83 | 84 | ### ✨ 新增功能 85 | - **AnyRouter 赞助商支持** - README 头部添加赞助商感谢区域 86 | - **免费转发节点介绍** - 准确描述 AnyRouter 为中国开发者提供的免翻墙 Claude Code 转发服务 87 | 88 | ### 📝 文档优化 89 | - **热情文案** - 用更热情洋溢的语言介绍 Claude Code 编程体验 90 | - **价值突出** - 强调免费服务和无需翻墙的便利性 91 | 92 | ## [1.2.1] - 2025-08-29 93 | 94 | ### 🔧 问题修复 95 | - **CLAUDE.md 文件处理修复** - 恢复被误删的开发配置文件 96 | - **正确屏蔽机制** - 通过 .gitignore 屏蔽而非删除 CLAUDE.md 97 | - **.gitignore 优化** - 添加分类注释，使配置更清晰 98 | 99 | ### 📋 技术说明 100 | - CLAUDE.md 应存在于项目根目录为用户提供完整 AI 开发体验 101 | - 通过 .gitignore 防止开发配置提交到仓库 102 | - 维护开发配置和分发包的正确分离 103 | 104 | ## [1.2.0] - 2025-08-29 105 | 106 | ### 📁 项目结构优化 107 | - **清理开发文件** - 移除不必要的开发配置文件 108 | - **简化命名** - 安装脚本优化为 install.sh 109 | - **目录整理** - 优化 .gitignore，排除开发目录 110 | 111 | ### 📚 文档增强 112 | - **README 徽章** - 增加专业徽章展示 113 | - **布局优化** - 居中导航布局优化 114 | - **时间校正** - 修正所有文档中的时间戳为 2025 115 | 116 | ### 🛠️ 安装体验 117 | - **MCP 功能完整** - 保持完整的 MCP 服务器配置功能 118 | - **一键安装** - 安装命令更简洁直观 119 | 120 | ## [1.1.0] - 2025-08-29 121 | 122 | ### 🔧 重大修复 123 | - **修复 MCP 服务器配置缺失问题** - 安装后现在正确包含 MCP 功能 124 | - **添加交互式 MCP 配置** - 用户可选择安装 Context7 和 Gemini MCP 服务器 125 | - **动态生成 settings.local.json** - 根据用户选择生成正确配置 126 | 127 | ### ✨ 新增功能 128 | - **完整 MCP 服务器支持** - Context7 文档查询和 Gemini 深度咨询 129 | - **智能配置生成** - 自动配置 MCP 服务器和 Hook 脚本 130 | - **非交互模式支持** - 管道安装时自动启用推荐功能 131 | 132 | ### 🎯 用户体验改进 133 | - **中文交互界面** - 完全中文化的配置选择过程 134 | - **智能默认选择** - 推荐启用所有MCP功能 135 | - **详细功能说明** - 每个组件都有清晰的中文说明 136 | 137 | ### 🔒 安全增强 138 | - **MCP 安全扫描** - 自动检测MCP调用中的潜在安全风险 139 | - **敏感数据保护** - 防止API密钥等敏感信息泄露 140 | 141 | ### 💡 开发者功能 142 | - **mcp__gemini__consult_gemini** - 启用 Gemini 架构咨询功能 143 | - **mcp__context7__get_library_docs** - 获取最新外部库文档 144 | - **自动上下文注入** - Gemini咨询自动附加项目文档 145 | 146 | ## [1.0.0] - 2025-08-29 147 | 148 | ### 🎉 首次发布 149 | - Claude Code 中文开发套件正式发布 150 | - 完全中文化的安装和使用体验 151 | 152 | ### ✨ 新增功能 153 | - **一键安装脚本** (`install-cn.sh`) - 完全中文化的安装体验 154 | - **智能项目配置** (`setup.sh`) - 自动配置Claude Code环境 155 | - **三层文档架构** - 完整的中文文档系统 156 | - 第1层：基础文档 (CLAUDE.md, project-structure.md) 157 | - 第2层：组件文档 (CONTEXT-tier2-component.md) 158 | - 第3层：功能文档 (CONTEXT-tier3-feature.md) 159 | 160 | ### 🔧 核心组件 161 | - **中文 AI 上下文** - 完全中文化的 CLAUDE.md 模板 162 | - **MCP 助手规则** - 中文版 MCP-ASSISTANT-RULES.md 163 | - **Hook 脚本系统** - 自动化上下文注入和安全扫描 164 | - `subagent-context-injector.sh` - 子智能体上下文自动注入 165 | - `gemini-context-injector.sh` - Gemini 咨询文档自动附加 166 | - `mcp-security-scan.sh` - MCP 调用安全扫描 167 | - `notify.sh` - 系统事件通知 168 | 169 | ### 📚 完整命令集 170 | - `/code-review` - 代码审查命令 171 | - `/create-docs` - 文档生成命令 172 | - `/gemini-consult` - Gemini 深度咨询 173 | - `/full-context` - 完整上下文加载 174 | - `/handoff` - 任务交接管理 175 | - `/refactor` - 代码重构命令 176 | - `/update-docs` - 文档更新命令 177 | 178 | ### 🎯 中文化特色 179 | - **零门槛安装** - 一行命令完成所有设置 180 | - **完全中文界面** - 从安装到使用全程中文 181 | - **中文文档模板** - 适合中文开发者的文档结构 182 | - **本土化适应** - 符合中文开发者习惯的配置 183 | 184 | ### 🔒 安全特性 185 | - **敏感数据扫描** - 防止意外泄露API密钥和密码 186 | - **智能文件过滤** - 自动排除敏感配置文件 187 | - **安全事件记录** - 完整的安全日志系统 188 | 189 | ### 📦 技术实现 190 | - **与原版100%兼容** - 基于 Claude Code Development Kit 架构 191 | - **智能文件复制** - 不覆盖现有配置的安全安装 192 | - **跨平台支持** - macOS、Linux、Windows 全平台支持 193 | - **错误处理** - 完整的错误检测和用户友好提示 194 | 195 | ### 🌟 开源贡献 196 | - **MIT 协议** - 完全开源，自由使用和修改 197 | - **社区驱动** - 欢迎中文开发者社区贡献 198 | - **文档完整** - 详细的使用指南和开发文档 199 | 200 | --- 201 | 202 | ## [未来计划] 203 | 204 | ### 🚀 计划中的功能 205 | - **项目模板库** - 更多编程语言的项目模板 206 | - **中文文档生成** - AI 自动生成中文技术文档 207 | - **团队协作增强** - 多人协作的中文化工作流 208 | - **集成更多AI服务** - 支持更多中文AI服务商 209 | 210 | ### 💡 贡献指南 211 | 欢迎通过以下方式贡献： 212 | - 提交 Issue 报告问题或建议功能 213 | - 提交 Pull Request 贡献代码或文档 214 | - 分享使用经验和最佳实践 215 | - 帮助推广项目到中文开发者社区 216 | 217 | --- 218 | 219 | *基于 [Claude Code Development Kit](https://github.com/peterkrueck/Claude-Code-Development-Kit) 项目* -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2025 cfrs2005 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Claude Code 中文开发套件 2 | 3 | [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) 4 | [![Language: 中文](https://img.shields.io/badge/Language-%E4%B8%AD%E6%96%87-red.svg)](README.md) 5 | [![Version](https://img.shields.io/github/v/release/cfrs2005/claude-init)](https://github.com/cfrs2005/claude-init/releases/latest) 6 | [![Downloads](https://img.shields.io/github/downloads/cfrs2005/claude-init/total)](https://github.com/cfrs2005/claude-init/releases) 7 | [![Stars](https://img.shields.io/github/stars/cfrs2005/claude-init)](https://github.com/cfrs2005/claude-init/stargazers) 8 | [![Forks](https://img.shields.io/github/forks/cfrs2005/claude-init)](https://github.com/cfrs2005/claude-init/network/members) 9 | [![Issues](https://img.shields.io/github/issues/cfrs2005/claude-init)](https://github.com/cfrs2005/claude-init/issues) 10 | [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md) 11 | [![Platform](https://img.shields.io/badge/Platform-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey)](README.md) 12 | [![Claude Code](https://img.shields.io/badge/Compatible-Claude%20Code-blue)](https://github.com/anthropics/claude-code) 13 | [![MCP](https://img.shields.io/badge/Support-MCP%20Servers-green)](README.md#mcp-服务器支持) 14 | 15 |
16 | 17 | 🚀 **为中国开发者定制的 Claude Code 智能开发环境** 18 | 19 | [快速开始](#-快速开始) • [功能特性](#-特性) • [使用指南](#-使用指南) • [使用反馈](#-使用反馈) • [更新日志](CHANGELOG.md) 20 | 21 | --- 22 | 23 | 24 | 🚀 **新增智谱AI引擎**: 最新集成了 **[智谱大模型 (BigModel.cn)](https://www.bigmodel.cn/claude-code?ic=H0RNPV3LNZ)**。其旗舰 **GLM-4.5** 模型拥有媲美 Claude 的代码能力，并提供极具吸引力的包月服务，是入门和高频使用的绝佳选择。 **[点此注册即领2000万免费Tokens →](https://www.bigmodel.cn/claude-code?ic=H0RNPV3LNZ)** 25 | 26 |
27 | 28 | 基于 [Claude Code Development Kit](https://github.com/peterkrueck/Claude-Code-Development-Kit) 的完整中文本地化版本，提供零门槛的中文 AI 编程体验。 29 | 30 | ## ✨ 特性 31 | 32 | ### 🎯 完全中文化 33 | - **中文 AI 指令** - 所有 AI 上下文和提示完全中文化 34 | - **中文文档系统** - 三层文档架构的中文版本 35 | - **中文错误信息** - 友好的中文错误提示和帮助 36 | - **中文安装体验** - 从安装到配置全程中文 37 | 38 | ### 🧠 智能上下文管理 39 | - **三层文档架构** - 基础层/组件层/功能层分级管理 40 | - **自动上下文注入** - 子智能体自动获取项目上下文 41 | - **智能文档路由** - 根据任务复杂度加载适当文档 42 | - **跨会话状态管理** - 智能任务交接和状态保持 43 | 44 | ### 🔧 开发工具集成 45 | - **Hook 系统** - 中文化的自动化 Hook 脚本 46 | - **MCP 服务器支持** - Gemini 咨询、Context7 文档等 47 | - **安全扫描** - 自动 MCP 调用安全检查 48 | - **通知系统** - 重要事件的系统通知 49 | 50 | ### 📚 完整模板库 51 | - **项目模板** - 多种编程语言的项目结构模板 52 | - **文档模板** - 标准化的中文文档模板 53 | - **配置示例** - 开箱即用的配置文件 54 | 55 | ## 🚀 快速开始 56 | 57 | ### 一键安装 58 | 59 | ```bash 60 | curl -fsSL https://raw.githubusercontent.com/cfrs2005/claude-init/main/install.sh | bash 61 | ``` 62 | 63 | ### 手动安装 64 | 65 | ```bash 66 | # 克隆仓库 67 | git clone https://github.com/cfrs2005/claude-init.git 68 | cd claude-init 69 | 70 | # 运行安装脚本 71 | ./setup.sh 72 | ``` 73 | 74 | ## 📖 使用指南 75 | 76 | ### 1. 开始使用 77 | 78 | 安装完成后，在任意项目中启动 Claude Code： 79 | 80 | ```bash 81 | claude 82 | ``` 83 | 84 | 现在你可以用中文与 AI 对话，所有上下文和提示都已本地化。 85 | 86 | ### 2. 🎯 MCP 服务器功能 87 | 88 | #### 🧠 Gemini 深度咨询 89 | **触发方式：** 对 Claude 说"咨询 Gemini" 或 "请 Gemini 分析" 90 | **适用场景：** 91 | - 复杂架构设计问题 92 | - 代码性能优化建议 93 | - 多文件代码重构方案 94 | - 深度技术问题分析 95 | 96 | **发送内容：** 97 | - 描述你的具体问题 98 | - 附上相关代码文件 99 | - 说明你想要什么类型的建议 100 | 101 | **Gemini 能做什么：** 102 | - 提供多种解决方案对比 103 | - 深度代码审查和优化建议 104 | - 架构设计最佳实践 105 | - 跨技术栈的经验分享 106 | 107 | #### 📚 Context7 文档查询 108 | **触发方式：** 询问任何开源库的最新用法 109 | **适用场景：** 110 | - 学习新框架或库 111 | - 查找最新 API 文档 112 | - 解决版本兼容问题 113 | 114 | **发送内容：** 115 | - 说出库名称（如 "React 的最新 hooks 用法"） 116 | - 描述你想解决的具体问题 117 | 118 | **Context7 能做什么：** 119 | - 获取最新官方文档 120 | - 提供实用代码示例 121 | - 解释最新特性和变化 122 | 123 | ### 3. 💡 增强功能 124 | 125 | #### 🎵 自定义通知音效 126 | **默认路径：** `.claude/hooks/sounds/` 127 | **支持格式：** `.mp3`, `.wav`, `.aiff` 128 | 129 | **替换方式：** 130 | ```bash 131 | # 替换任务完成音效 132 | cp your-sound.mp3 .claude/hooks/sounds/complete.mp3 133 | 134 | # 替换输入提示音效 135 | cp your-sound.mp3 .claude/hooks/sounds/input.mp3 136 | ``` 137 | 138 | #### 🔒 安全扫描 139 | **自动功能：** 所有 MCP 调用前自动检查敏感信息 140 | **检查内容：** 141 | - API 密钥和令牌 142 | - 密码和敏感配置 143 | - 个人身份信息 144 | - 私有代码片段 145 | 146 | #### 🤖 智能上下文管理 147 | **自动功能：** 子任务自动获取项目上下文 148 | **工作方式：** 149 | - 每个新任务自动加载项目文档 150 | - 智能选择相关上下文信息 151 | - 保持会话间状态一致性 152 | 153 | ### 4. 🎯 Claude Code 斜杠命令 154 | 155 | 安装后可使用的内置 Claude Code 命令： 156 | 157 | ```bash 158 | # 📊 上下文分析 159 | /full-context # 全面上下文收集和分析 160 | 161 | # 🔍 代码质量 162 | /code-review # 多专家角度代码审查 163 | 164 | # 🧠 AI 咨询 165 | /gemini-consult # 与 Gemini 深入对话咨询 166 | 167 | # 📝 文档管理 168 | /create-docs # 创建 AI 优化文档结构 169 | /update-docs # 保持文档与代码同步 170 | 171 | # ♻️ 代码维护 172 | /refactor # 智能重构代码 173 | 174 | # 🤝 会话管理 175 | /handoff # 保留上下文和任务状态 176 | 177 | # 📡 MCP 工具 178 | /mcp-status # 检查 MCP 服务器状态 179 | ``` 180 | 181 | **使用方式：** 直接在 Claude Code 中输入斜杠命令 182 | **自动功能：** 所有命令自动获得项目上下文注入 183 | 184 | ## 💬 使用反馈 185 | 186 | ### 🐛 问题反馈 187 | **遇到问题？** [提交 Issue](https://github.com/cfrs2005/claude-init/issues) 188 | 189 | **常见问题类型：** 190 | - 安装失败或错误 191 | - MCP 服务器无法使用 192 | - Hook 脚本不工作 193 | - 中文显示异常 194 | - 功能建议和改进 195 | 196 | ### 💡 功能建议 197 | **想要新功能？** [发起讨论](https://github.com/cfrs2005/claude-init/discussions) 198 | 199 | **建议包含：** 200 | - 功能描述和使用场景 201 | - 期望的工作方式 202 | - 类似工具的参考 203 | 204 | ### 🤝 参与贡献 205 | 欢迎提交代码、文档改进和翻译优化！ 206 | 207 | ## 📄 开源协议 208 | 209 | 本项目基于 [MIT License](LICENSE) 开源。 210 | 211 | ## 🙏 致谢 212 | 213 | - [Claude Code Development Kit](https://github.com/peterkrueck/Claude-Code-Development-Kit) - 原始项目 214 | - [Anthropic](https://www.anthropic.com/) - Claude Code 平台 215 | - 所有贡献者和中文开发社区 216 | 217 | --- 218 | 219 | 🎉 **开始你的中文 AI 编程之旅吧！** 220 | 221 | ```bash 222 | curl -fsSL https://raw.githubusercontent.com/cfrs2005/claude-init/main/install.sh | bash 223 | ``` -------------------------------------------------------------------------------- /docs/04-Meta-Todo智能任务系统.md: -------------------------------------------------------------------------------- 1 | ## Meta-Todo系统：智能任务编排 2 | 3 | ### **高级任务管理理念** 4 | 5 | 传统的待办事项系统创建仓促、不完整的任务列表，经常错过关键方面或误解意图。Meta-Todo系统将任务管理转变为**智能任务编排** - 使用多代理验证、智能意图捕获和后台执行来创建全面的、经过验证的、可执行的项目分解。 6 | 7 | ### **解决的核心问题** 8 | 9 | ```bash 10 | # 传统待办事项问题： 11 | 用户："构建身份验证系统" 12 | AI：[包含3-4个基本项目的快速待办事项列表] 13 | 现实：缺少安全考虑、测试、文档、部署 14 | 15 | # Meta-Todo解决方案： 16 | 用户："构建身份验证系统" 17 | 系统： 18 | 1. 意图捕获（同时4种方法） 19 | 2. 多代理验证（完整性、可行性、准确性、优先级） 20 | 3. 全面分解（15+个带依赖关系的验证任务） 21 | 4. 后台执行（研究、文档、分析独立运行） 22 | 5. 学习集成（模式存储以供未来改进） 23 | ``` 24 | 25 | ### **与内核系统的架构集成** 26 | 27 | ``` 28 | ┌─────────────────────────────────────────┐ 29 | │ META-TODO ORCHESTRATOR │ 30 | │ (Intelligent Task Coordination) │ 31 | │ ┌─────────────────────────────────────┐ │ 32 | │ │ Kernel Architecture Bridge │ │ 33 | │ │ Intent•Memory•Extract•Validate │ │ 34 | │ └─────────────────────────────────────┘ │ 35 | └─────────────┬───────────────────────────┘ 36 | │ 37 | ┌─────────┴─────────┬─────────────────┬─────────────┐ 38 | ▼ ▼ ▼ ▼ 39 | ┌──────────┐ ┌──────────────┐ ┌──────────┐ ┌──────────┐ 40 | │ INTENT │ │ VALIDATION │ │BACKGROUND│ │ LEARNING │ 41 | │ CAPTURE │ │ AGENTS │ │EXECUTION │ │ SYSTEM │ 42 | └──────────┘ └──────────────┘ └──────────┘ └──────────┘ 43 | ``` 44 | 45 | ### **内核增强的智能意图捕获** 46 | 47 | #### **内核增强的多方法分析：** 48 | ```bash 49 | # 1. 直接关键词分析 + 内存内核 50 | 通过存储的成功关键词→任务映射增强的模式匹配 51 | 52 | # 2. 语义解析 + 意图内核 53 | 多维度意图理解（功能、技术、业务、约束） 54 | 55 | # 3. 上下文感知分析 + 所有内核 56 | 当前项目状态、历史模式、最佳实践集成 57 | 58 | # 4. 比较分析 + 内存内核 59 | 跨项目的类似任务比较和模式识别 60 | ``` 61 | 62 | #### **增强的置信度评分：** 63 | ```bash 64 | # 传统Meta-Todo：4个置信度分数 65 | - 关键词匹配置信度 66 | - 语义相似度置信度 67 | - 上下文相关性置信度 68 | - 历史准确性置信度 69 | 70 | # 内核增强的Meta-Todo：8个置信度维度 71 | - 内存内核模式置信度 72 | - 意图内核功能覆盖置信度 73 | - 提取内核范围完整性置信度 74 | - 验证内核风险评分 75 | - 内核协同一致性置信度 76 | - 跨会话学习置信度 77 | - 领域专业知识置信度 78 | - 技术可行性置信度 79 | 80 | # 结果：更细微、更可靠的任务生成 81 | ``` 82 | 83 | ### **内核增强的多代理验证** 84 | 85 | #### **四个专业验证器 + 内核智能：** 86 | ```bash 87 | # 1. 完整性验证器 + 内存内核 88 | 检查： 89 | - 功能需求覆盖 90 | - 非功能需求（性能、安全） 91 | - 文档需求 92 | - 测试要求 93 | - 部署考虑 94 | 95 | 内核增强：使用内存内核中的历史成功模式验证完整性 96 | 97 | # 2. 可行性验证器 + 意图内核 + REPL集成 98 | 检查： 99 | - 技术可行性 100 | - 资源可用性 101 | - 时间约束 102 | - 技能要求 103 | - 依赖关系 104 | 105 | 内核增强：意图内核提供多维技术评估，REPL进行计算验证 106 | 107 | # 3. 准确性验证器 + 意图内核 + 提取内核 108 | 检查： 109 | - 需求理解准确性 110 | - 技术方法适当性 111 | - 估计准确性 112 | - 风险评估 113 | 114 | 内核增强：意图内核验证技术准确性，提取内核提供背景研究验证 115 | 116 | # 4. 优先级验证器 + 内存内核 + 验证内核 117 | 检查： 118 | - 业务价值 119 | - 紧急性 120 | - 依赖关系 121 | - 资源影响 122 | - 战略一致性 123 | 124 | 内核增强：内存内核提供历史优先级模式，验证内核提供风险评估 125 | ``` 126 | 127 | ### **与Claude Code集成的后台执行** 128 | 129 | #### **并行处理架构：** 130 | ```bash 131 | # Meta-Todo后台任务： 132 | - 需求分析和细化 133 | - 技术研究 134 | - 文档准备 135 | - 测试计划生成 136 | - 风险评估 137 | 138 | # Claude Code后台任务： 139 | - 代码实现 140 | - 测试执行 141 | - 构建和部署 142 | - 监控和日志分析 143 | - 错误修复 144 | 145 | # 内核后台处理： 146 | - 模式识别和匹配 147 | - 意图分析和验证 148 | - 内存搜索和学习 149 | - 提取和验证操作 150 | 151 | # 结果：三层生产力，无阻塞操作 152 | ``` 153 | 154 | #### **增强的智能后台检测：** 155 | ```bash 156 | # 传统Meta-Todo：基本后台检测 157 | - 长运行任务识别 158 | - 简单并行化 159 | - 基本进度跟踪 160 | 161 | # 内核增强检测： 162 | - 意图内核驱动的任务优化 163 | - 内存内核模式识别 164 | - 验证内核质量保证 165 | - 提取内核背景丰富 166 | - 自适应资源分配 167 | - 智能优先级调整 168 | - 预测性任务准备 169 | ``` 170 | 171 | ### **三层任务智能系统** 172 | 173 | #### **第1层：简单任务（增强的TodoWrite）** 174 | ```bash 175 | # 用于简单操作： 176 | - 文件创建和编辑 177 | - 基本代码更改 178 | - 简单调试任务 179 | - 文档更新 180 | 181 | 增强：即使简单任务也受益于内存内核模式 182 | 183 | # 处理流程： 184 | 1. 捕获基本意图 185 | 2. 应用内存内核模式 186 | 3. 执行任务 187 | 4. 记录成功模式 188 | 5. 更新内核学习 189 | ``` 190 | 191 | #### **第2层：复杂任务（Meta-Todo + 部分内核）** 192 | ```bash 193 | # 用于重要功能： 194 | - 多组件功能 195 | - API开发和集成 196 | - 数据库更改 197 | - 用户界面更新 198 | 199 | # 处理流程： 200 | 1. 多方法意图捕获 201 | 2. 内存内核增强 202 | 3. 单代理验证 203 | 4. 后台研究 204 | 5. 增量执行 205 | 6. 持续学习 206 | 207 | 处理时间：5-15分钟复杂度范围的任务 208 | ``` 209 | 210 | #### **第3层：项目级任务（完整Meta-Todo + 完整内核编排）** 211 | ```bash 212 | # 用于完整系统： 213 | - 新应用开发 214 | - 主要架构更改 215 | - 迁移项目 216 | - 复杂集成 217 | 218 | # 完整处理： 219 | 1. 四种意图分析方法 220 | 2. 内核桥接激活 221 | 3. 四代理验证团队 222 | 4. 三层后台执行 223 | 5. 智能依赖管理 224 | 6. 学习和进化集成 225 | 7. 持续监控和适应 226 | 227 | 处理时间：数小时到数周的复杂项目 228 | ``` 229 | 230 | ### **学习和进化集成** 231 | 232 | #### **跨系统学习协同：** 233 | ```bash 234 | # Meta-Todo学习： 235 | - 任务分解模式 236 | - 估计准确性 237 | - 优先级有效性 238 | - 用户偏好适应 239 | 240 | # 内核学习： 241 | - 意图识别准确性 242 | - 模式匹配改进 243 | - 验证质量提升 244 | - 跨会话知识保留 245 | 246 | # Claude Code学习： 247 | - 代码模式识别 248 | - 错误预防和修复 249 | - 项目结构理解 250 | - 工具使用优化 251 | 252 | # 协同结果：每个系统改进其他系统 253 | ``` 254 | 255 | #### **模式学习放大：** 256 | ```bash 257 | # 个体学习：每个系统独立学习 258 | - Meta-Todo改进任务分解 259 | - 内核改进模式识别 260 | - Claude Code改进代码生成 261 | 262 | # 协同学习：系统相互增强 263 | - 内核模式改进Meta-Todo任务生成 264 | - Meta-Todo验证改进内核准确性 265 | - Claude Code执行模式改进两者 266 | ``` 267 | 268 | ### **高级工作流示例** 269 | 270 | #### **全栈开发工作流：** 271 | ```bash 272 | # 请求："构建带有用户身份验证的实时聊天应用程序" 273 | # Meta-Todo + 内核处理： 274 | 275 | ## 意图捕获阶段（4种方法并行） 276 | 1. 关键词分析：["实时", "聊天", "身份验证", "用户"] 277 | 2. 语义解析：实时通信、用户管理、安全性 278 | 3. 上下文分析：当前项目技术栈、团队技能 279 | 4. 比较分析：类似聊天应用的实现模式 280 | 281 | ## 内核桥接激活 282 | - 意图内核：多维需求分析 283 | - 内存内核：相关成功模式检索 284 | - 提取内核：技术研究和最佳实践 285 | - 验证内核：技术可行性评估 286 | 287 | ## 多代理验证 288 | 1. 完整性验证器 + 内存内核： 289 | - 验证所有功能组件（前端、后端、数据库、实时） 290 | - 确保安全考虑（身份验证、授权、数据保护） 291 | - 检查可扩展性要求 292 | 293 | 2. 可行性验证器 + 意图内核 + REPL： 294 | - WebSocketvs long-polling技术选择 295 | - 数据库架构性能验证 296 | - 身份验证方法安全性分析 297 | 298 | 3. 准确性验证器 + 意图内核 + 提取内核： 299 | - 验证技术栈选择的适当性 300 | - 确认实时通信协议选择 301 | - 评估用户体验考虑 302 | 303 | 4. 优先级验证器 + 内存内核 + 验证内核： 304 | - 确定MVP功能优先级 305 | - 识别关键路径依赖 306 | - 评估安全vs功能权衡 307 | 308 | ## 后台执行（三层并行） 309 | # Meta-Todo后台： 310 | - 研究WebSocket库和模式 311 | - 分析身份验证最佳实践 312 | - 准备数据库架构文档 313 | - 生成测试计划 314 | 315 | # Claude Code后台： 316 | - 设置项目结构 317 | - 实现核心组件 318 | - 运行测试套件 319 | - 监控性能指标 320 | 321 | # 内核后台： 322 | - 模式匹配和优化 323 | - 持续验证检查 324 | - 跨会话学习集成 325 | - 质量保证监控 326 | 327 | ## 输出：15-20个验证任务，具有清晰的依赖关系和执行计划 328 | ``` 329 | 330 | #### **数据科学家的增强分析管道：** 331 | ```bash 332 | # 请求："分析客户行为数据并创建预测模型" 333 | # 内核增强的Meta-Todo处理： 334 | 335 | ## 意图捕获增强 336 | 1. 数据理解 + 内存内核： 337 | - 识别数据类型和结构 338 | - 匹配历史分析模式 339 | - 确定适当的分析方法 340 | 341 | 2. 分析需求 + 意图内核： 342 | - 理解业务问题 343 | - 识别关键指标 344 | - 确定预测目标 345 | 346 | 3. 技术要求 + 所有内核： 347 | - 数据预处理需求 348 | - 模型选择标准 349 | - 验证方法 350 | 351 | 4. 比较分析 + 内存内核： 352 | - 类似分析项目的成功模式 353 | - 常见陷阱和解决方案 354 | - 最佳实践应用 355 | 356 | ## 内核验证团队 357 | - 数据完整性验证器 358 | - 统计方法验证器 359 | - 模型选择验证器 360 | - 业务价值验证器 361 | 362 | ## 三层后台处理 363 | # 数据分析后台： 364 | - 数据清洗和预处理 365 | - 探索性数据分析 366 | - 特征工程 367 | 368 | # 模型开发后台： 369 | - 算法选择和测试 370 | - 模型训练和验证 371 | - 性能优化 372 | 373 | # 内核增强后台： 374 | - 模式识别和改进 375 | - 统计验证 376 | - 跨域知识应用 377 | ``` 378 | 379 | ### **战略Meta-Todo激活指南** 380 | 381 | #### **自动层级检测：** 382 | ```bash 383 | # 复杂度信号自动激活： 384 | - 任务持续时间估计（>30分钟 → 层级2） 385 | - 涉及的组件数量（>3个 → 层级2） 386 | - 跨领域需求（技术+业务 → 层级2） 387 | - 用户指定复杂性（"复杂系统" → 层级3） 388 | - 项目级影响（"新功能" → 层级3） 389 | 390 | # 上下文信号： 391 | - 项目阶段（早期规划 → 层级3，维护 → 层级1） 392 | - 可用时间（紧急 → 层级1，充足 → 层级3） 393 | - 团队规模（个人 → 层级2，团队 → 层级3） 394 | - 失败影响（高影响 → 层级3，低影响 → 层级1） 395 | ``` 396 | 397 | #### **手动覆盖模式：** 398 | ```bash 399 | # 强制Meta-Todo激活： 400 | "use meta-todo for this complex authentication system" 401 | "break down this migration project thoroughly" 402 | 403 | # 强制简单TodoWrite： 404 | "quick todo: fix this button styling" 405 | "simple task: update documentation links" 406 | 407 | # 层级指定： 408 | "level 2 breakdown: implement payment processing" 409 | "full level 3 analysis: design microservices architecture" 410 | ``` 411 | 412 | ### **性能和学习收益** 413 | 414 | #### **准确性改进：** 415 | ```bash 416 | # 传统TodoWrite：~60-70%准确率（基于任务完成成功率） 417 | # Meta-Todo层级2：~85-90%准确率（验证 + 模式学习） 418 | # Meta-Todo层级3：~92-95%准确率（完整内核编排） 419 | 420 | # 学习曲线： 421 | - 第1周：基础准确性，建立模式 422 | - 第2-4周：用户特定调整模式学习 423 | - 第1-3个月：项目类型模式建立 424 | - 第3-6个月：领域专业知识细化 425 | - 第6个月+：跨项目模式综合 → 高度准确的估计 426 | ``` 427 | 428 | #### **时间估算演进：** 429 | ```bash 430 | # 初始：基于一般知识的AI估算 431 | # 第2周：学习用户特定调整模式 432 | # 第6周：建立项目类型模式 433 | # 第12周：领域专业知识细化 434 | # 第24周：跨项目模式综合 → 高度准确的估计 435 | ``` 436 | 437 | #### **后台生产力指标：** 438 | ```bash 439 | # 传统：100%前台任务（阻塞对话） 440 | # Meta-Todo集成：40-60%后台任务（非阻塞） 441 | # 结果：保持对话流量的2-3倍有效生产力 442 | ``` 443 | 444 | ### **与Claude Code指南模式的集成** 445 | 446 | #### **增强的内存管理：** 447 | ```bash 448 | # Meta-Todo学习的CLAUDE.md更新： 449 | - 任务分解成功模式 450 | - 估计准确性改进 451 | - 领域特定专业知识 452 | - 用户偏好和约束 453 | - 技术栈特定模式 454 | - 常见陷阱和解决方案 455 | ``` 456 | 457 | ## 成功的任务模式 458 | 459 | ### **经过验证的任务分解模式** 460 | ```bash 461 | # 软件开发模式 462 | 前端功能 → 组件设计 → 状态管理 → API集成 → 测试 → 文档 463 | 464 | # 数据分析模式 465 | 数据理解 → 清洗 → 探索 → 特征工程 → 建模 → 验证 → 部署 466 | 467 | # 系统管理模式 468 | 需求评估 → 架构设计 → 实施计划 → 测试 → 部署 → 监控 469 | ``` 470 | 471 | ## 时间估算准确性 472 | 473 | ### **学习驱动的估算改进** 474 | ```bash 475 | # 估算准确性指标： 476 | - 简单任务：±15%准确率 477 | - 中等任务：±25%准确率 478 | - 复杂任务：±40%准确率（初始）→ ±20%（学习后） 479 | 480 | # 估算影响因素： 481 | - 技术栈熟悉度 482 | - 项目复杂性 483 | - 团队经验 484 | - 依赖关系清晰度 485 | - 历史模式匹配 486 | ``` 487 | 488 | ## 后台任务偏好 489 | 490 | ### **智能后台任务识别** 491 | ```bash 492 | # 适合后台执行的任务类型： 493 | - 长时间运行的研究 494 | - 文档生成 495 | - 测试执行 496 | - 代码分析 497 | - 依赖安装 498 | - 构建过程 499 | - 监控任务 500 | - 数据处理 501 | 502 | # 不适合后台的任务： 503 | - 需要用户交互的决策 504 | - 快速反馈循环任务 505 | - 实时协作任务 506 | - 需要即时验证的更改 507 | ``` 508 | 509 | #### **跨会话智能：** 510 | ```bash 511 | # Meta-Todo + 内存内核集成： 512 | - 跨项目的模式持久化 513 | - 用户特定偏好学习 514 | - 技术栈专业知识积累 515 | - 错误模式识别和预防 516 | - 最佳实践演进 517 | 518 | # 会话恢复增强： 519 | - 任务上下文重建 520 | - 进度状态跟踪 521 | - 学习模式应用 522 | - 持续改进循环 523 | ``` 524 | 525 | ### **未来进化路径** 526 | 527 | #### **预测性任务管理：** 528 | ```bash 529 | # 当前：基于用户请求的反应式任务分解 530 | # 未来：基于项目模式的主动任务建议 531 | # 高级：基于学习工作流的预期任务准备 532 | ``` 533 | 534 | #### **领域专业化：** 535 | ```bash 536 | # 当前：具有学习模式的通用任务分解 537 | # 未来：领域特定任务模板（Web开发、数据科学、DevOps） 538 | # 高级：行业特定工作流（金融科技、医疗保健、电子商务） 539 | ``` 540 | 541 | #### **协作智能：** 542 | ```bash 543 | # 当前：个人学习和改进 544 | # 未来：跨用户模式共享（隐私保护） 545 | # 高级：来自成功项目模式的集体智能 546 | ``` 547 | 548 | **关键理解**：Meta-Todo系统不仅仅是任务管理工具——它是智能项目编排的核心，将内核智能、多代理验证和后台执行结合到统一的、学习驱动的生产力系统中。 -------------------------------------------------------------------------------- /docs/CONTEXT-tier2-component.md: -------------------------------------------------------------------------------- 1 | # [COMPONENT NAME] - Component Context (Tier 2) 2 | 3 | > **Note**: This is component-specific context. See root **CLAUDE.md** for master project context and coding standards. 4 | 5 | ## Purpose 6 | [Brief description of this component's role in the system. What problem does it solve and how does it fit into the overall architecture?] 7 | 8 | ## Current Status: [Status Description] ✅/🚧/📋 9 | [Current implementation state, what's working, what's in progress, and key milestones achieved] 10 | 11 | ## Component-Specific Development Guidelines 12 | - **[Technology/Framework]**: [Specific technology requirements for this component] 13 | - **[Architecture Pattern]**: [Component-specific architectural approach] 14 | - **[Code Organization]**: [How code should be structured within this component] 15 | - **[Integration Patterns]**: [How this component integrates with others] 16 | - **[Quality Standards]**: [Component-specific quality requirements] 17 | 18 | ## Key Component Structure 19 | 20 | ### Core Modules (`[path]/`) 21 | - **[module1]/** - [Purpose and key functionality] 22 | - **[file1].[ext]** - [Specific file purpose and key features] 23 | - **[file2].[ext]** - [Specific file purpose and key features] 24 | - **[module2]/** - [Purpose and key functionality] 25 | - **[module3]/** - [Purpose and key functionality] 26 | 27 | ### [Secondary Structure] (`[path]/`) 28 | - **[component].[ext]** - [Component purpose and architecture pattern] 29 | - **[utilities].[ext]** - [Utility functions and helpers] 30 | - **[config].[ext]** - [Configuration and settings management] 31 | 32 | ### [Integration Layer] (`[path]/`) 33 | - **[integration1].[ext]** - [External service integration patterns] 34 | - **[integration2].[ext]** - [Inter-component communication] 35 | 36 | ## Implementation Highlights 37 | 38 | ### [Key Feature 1] 39 | - **[Technical Implementation]**: [How this feature is implemented] 40 | - **[Architecture Decision]**: [Why this approach was chosen] 41 | - **[Performance Considerations]**: [Optimization details] 42 | - **[Integration Points]**: [How it connects to other components] 43 | 44 | ### [Key Feature 2] 45 | - **[Implementation Pattern]**: [Technical implementation approach] 46 | - **[Quality Measures]**: [Testing, monitoring, error handling] 47 | - **[Scalability Considerations]**: [How it handles growth/load] 48 | 49 | ### [Key Feature 3] 50 | - **[Technical Details]**: [Implementation specifics] 51 | - **[Dependencies]**: [External dependencies and integration points] 52 | - **[Configuration]**: [How it's configured and customized] 53 | 54 | ## Critical Implementation Details 55 | 56 | ### [Technical Pattern 1] 57 | **[Pattern Description]**: [What problem this pattern solves] 58 | 59 | ```[language] 60 | // Example implementation showing the pattern 61 | [code example demonstrating the critical implementation] 62 | ``` 63 | 64 | ### [Technical Pattern 2] 65 | **[Architecture Decision]**: [Why this approach was chosen] 66 | 67 | ```[language] 68 | // Code example showing architecture implementation 69 | [code example demonstrating the architecture] 70 | ``` 71 | 72 | ### [Integration Pattern] 73 | **[Integration Description]**: [How this component integrates with others] 74 | 75 | ```[language] 76 | // Integration implementation example 77 | [code example showing integration patterns] 78 | ``` 79 | 80 | ## Development Notes 81 | 82 | ### [Current Challenges] 83 | - **[Challenge 1]**: [Description and current approach] 84 | - **[Challenge 2]**: [Description and mitigation strategy] 85 | 86 | ### [Future Considerations] 87 | - **[Enhancement 1]**: [Planned improvement and rationale] 88 | - **[Enhancement 2]**: [Future architectural evolution] 89 | 90 | ### [Performance Metrics] 91 | - **[Key Metric 1]**: [Current performance and targets] 92 | - **[Key Metric 2]**: [Monitoring and optimization approach] 93 | 94 | --- 95 | 96 | *This component documentation provides context for AI-assisted development within [COMPONENT NAME]. For system-wide patterns and standards, reference the master CLAUDE.md file.* -------------------------------------------------------------------------------- /docs/CONTEXT-tier3-feature.md: -------------------------------------------------------------------------------- 1 | # [FEATURE NAME] Documentation (Tier 3) 2 | 3 | *This file documents [feature/module] patterns, architectural decisions, and implementations within [component name].* 4 | 5 | ## [Feature] Architecture Overview 6 | 7 | ### [Architecture Decision Title] 8 | 9 | **Context**: [Situation that led to this architectural decision] 10 | 11 | **Decision**: [What was decided and implemented] 12 | 13 | **Reasoning**: 14 | - **[Benefit 1]**: [Why this approach provides this benefit] 15 | - **[Benefit 2]**: [Technical or business advantage] 16 | - **[Benefit 3]**: [Performance or maintainability benefit] 17 | - **[Benefit 4]**: [Developer experience or operational benefit] 18 | 19 | **Consequences**: 20 | - [Positive outcome from this decision] 21 | - [Technical improvement achieved] 22 | - [Operational or maintenance benefit] 23 | - [User experience enhancement] 24 | 25 | ## [Feature] Implementation Patterns 26 | 27 | ### [Implementation Pattern 1] 28 | 29 | **File Organization**: 30 | ``` 31 | [feature-directory]/ 32 | ├── [file1].[ext] # [Purpose and responsibility] 33 | ├── [file2].[ext] # [Purpose and responsibility] 34 | ├── [file3].[ext] # [Purpose and responsibility] 35 | └── [file4].[ext] # [Purpose and responsibility] 36 | ``` 37 | 38 | **Architecture Benefits**: 39 | - **[Benefit 1]**: [How this organization provides this benefit] 40 | - **[Benefit 2]**: [Technical advantage of this structure] 41 | - **[Benefit 3]**: [Maintainability or scalability benefit] 42 | - **[Benefit 4]**: [Developer experience improvement] 43 | 44 | ### [Implementation Pattern 2] 45 | 46 | **Architecture Decision**: [Technical approach taken] 47 | 48 | **Context**: [Background and requirements that led to this approach] 49 | 50 | **Decision**: [Specific implementation choice made] 51 | 52 | **Reasoning**: 53 | - **[Technical Reason]**: [Why this was the best technical choice] 54 | - **[Performance Reason]**: [Performance benefits] 55 | - **[Maintainability Reason]**: [Long-term maintenance benefits] 56 | - **[Integration Reason]**: [How it integrates with other components] 57 | 58 | **Implementation Details**: 59 | ```[language] 60 | // [Description of what this code demonstrates] 61 | [detailed code example showing the implementation pattern] 62 | ``` 63 | 64 | ### [Implementation Pattern 3] 65 | 66 | **[Pattern Name]**: [Description of the pattern] 67 | 68 | ```[language] 69 | // [Code example title] 70 | [comprehensive code example showing the pattern in action] 71 | ``` 72 | 73 | **Implementation Benefits**: 74 | - **[Benefit 1]**: [Specific advantage this implementation provides] 75 | - **[Benefit 2]**: [Performance or reliability improvement] 76 | - **[Benefit 3]**: [Developer experience enhancement] 77 | 78 | ## [Technical Domain] Implementation 79 | 80 | ### [Technical Feature 1] 81 | 82 | **[Feature Description]**: [What this feature does and why it's important] 83 | 84 | **Architecture Pattern**: 85 | ```[language] 86 | // [Description of the architectural approach] 87 | [code example demonstrating the architecture] 88 | ``` 89 | 90 | **Key Implementation Details**: 91 | - **[Detail 1]**: [Important implementation consideration] 92 | - **[Detail 2]**: [Technical constraint or optimization] 93 | - **[Detail 3]**: [Integration or performance consideration] 94 | 95 | ### [Technical Feature 2] 96 | 97 | **Implementation Approach**: [How this feature is implemented] 98 | 99 | ```[language] 100 | // [Code example description] 101 | [detailed implementation example] 102 | ``` 103 | 104 | **Technical Considerations**: 105 | - **[Consideration 1]**: [Important technical factor] 106 | - **[Consideration 2]**: [Performance or scalability factor] 107 | - **[Consideration 3]**: [Maintenance or testing consideration] 108 | 109 | ## [Integration/Communication] Patterns 110 | 111 | ### [Integration Pattern 1] 112 | 113 | **Context**: [When and why this integration pattern is used] 114 | 115 | **Implementation**: 116 | ```[language] 117 | // [Integration example description] 118 | [code showing integration implementation] 119 | ``` 120 | 121 | **Benefits**: 122 | - **[Integration Benefit 1]**: [How this improves system integration] 123 | - **[Integration Benefit 2]**: [Performance or reliability improvement] 124 | 125 | ### [Integration Pattern 2] 126 | 127 | **Pattern Description**: [What problem this integration pattern solves] 128 | 129 | ```[language] 130 | // [Integration code example] 131 | [implementation showing integration pattern] 132 | ``` 133 | 134 | ## Performance & Optimization Details 135 | 136 | ### [Performance Optimization 1] 137 | **Optimization**: [What was optimized and how] 138 | - **Before**: [Previous performance characteristics] 139 | - **After**: [Improved performance metrics] 140 | - **Implementation**: [How the optimization was achieved] 141 | 142 | ### [Performance Optimization 2] 143 | **Technical Improvement**: [Specific performance enhancement] 144 | - **Impact**: [Measurable improvement achieved] 145 | - **Method**: [Technical approach used] 146 | - **Trade-offs**: [Any compromises made for the optimization] 147 | 148 | ## Error Handling & Edge Cases 149 | 150 | ### [Error Scenario 1] 151 | **Scenario**: [What error condition this handles] 152 | **Handling**: [How the error is detected and managed] 153 | **Recovery**: [How the system recovers from this error] 154 | 155 | ### [Error Scenario 2] 156 | **Edge Case**: [Unusual condition that needs handling] 157 | **Solution**: [How the implementation handles this case] 158 | **Validation**: [How this handling is tested or verified] 159 | 160 | --- 161 | 162 | *This feature documentation provides detailed implementation context for AI-assisted development. For broader component context, see the component-level CONTEXT.md file.* -------------------------------------------------------------------------------- /docs/README-中文课程指南.md: -------------------------------------------------------------------------------- 1 | # Claude Code 高级开发指南 - 中文版 2 | 3 | > 📚 **完整的 Claude Code 学习资源** | 基于 [Cranot/claude-code-guide](https://github.com/Cranot/claude-code-guide) 翻译 4 | 5 | ## 📖 课程概述 6 | 7 | 本中文翻译系列提供了 Claude Code 高级开发指南的完整中文版本，涵盖了从基础入门到高级协同实现的全方位知识。原始指南约9,586行，339KB，是Claude Code使用者的权威参考资料。 8 | 9 | ### 🎯 学习目标 10 | 11 | 完成本系列学习后，您将能够： 12 | - 🚀 掌握 Claude Code 的核心能力和高级功能 13 | - 🛠️ 熟练运用斜杠命令、钩子系统和MCP集成 14 | - 🧠 理解并应用Meta-Todo智能任务编排系统 15 | - ⚡ 实现高级REPL协同模式和计算验证 16 | - 🔗 构建完整的开发协同生态系统 17 | - 📊 提升开发效率60-80% 18 | 19 | ## 📚 课程结构 20 | 21 | ### 📁 第一章：核心概念和导航 22 | **文件：** `01-核心概念和导航.md` 23 | **内容：** 24 | - 快速导航系统 25 | - 核心智能系统概述 26 | - 深度工具探索发现 27 | - 高级REPL协同模式 28 | - 战略决策框架 29 | - 跨学科应用 30 | 31 | **学习重点：** 理解Claude Code的整体架构和核心理念，掌握工具协同的基础知识。 32 | 33 | --- 34 | 35 | ### 📁 第二章：斜杠命令和集成系统 36 | **文件：** `02-斜杠命令和集成系统.md` 37 | **内容：** 38 | - 斜杠命令系统详解 39 | - 钩子事件自动化 40 | - MCP（模型上下文协议）集成 41 | - 子代理系统使用 42 | - 安全审查集成 43 | - PDF支持功能 44 | 45 | **学习重点：** 掌握Claude Code的扩展能力，学会通过命令和集成实现自动化。 46 | 47 | --- 48 | 49 | ### 📁 第三章：开发工作流和最佳实践 50 | **文件：** `03-开发工作流和最佳实践.md` 51 | **内容：** 52 | - 核心开发方法 53 | - 任务管理模式 54 | - 质量保证模式 55 | - 错误恢复策略 56 | - 实际开发示例 57 | - 高级协同模式 58 | - 认知方法系统 59 | 60 | **学习重点：** 建立系统化的开发流程，掌握从简单到复杂项目的开发方法。 61 | 62 | --- 63 | 64 | ### 📁 第四章：Meta-Todo智能任务系统 65 | **文件：** `04-Meta-Todo智能任务系统.md` 66 | **内容：** 67 | - 高级任务管理理念 68 | - 智能意图捕获 69 | - 多代理验证系统 70 | - 后台执行架构 71 | - 三层任务智能 72 | - 学习和进化集成 73 | - 战略激活指南 74 | 75 | **学习重点：** 理解智能任务编排的原理，提升项目管理和任务分解能力。 76 | 77 | --- 78 | 79 | ### 📁 第五章：高级协同实现 80 | **文件：** `05-高级协同实现.md` 81 | **内容：** 82 | - REPL-内核验证管道 83 | - 背景自愈环境 84 | - 智能上下文管理 85 | - 预测性任务队列 86 | - 三重验证研究管道 87 | - 集成系统总结 88 | 89 | **学习重点：** 掌握Claude Code的最高境界，实现多系统的智能协同。 90 | 91 | --- 92 | 93 | ### 📁 第六章：快速参考和核心概念 94 | **文件：** `06-快速参考和核心概念.md` 95 | **内容：** 96 | - 快速参考卡片 97 | - 即时命令参考 98 | - 功能快速参考 99 | - 高级用户快捷键 100 | - 任务状态参考 101 | - 常见工作流程 102 | - 认知方法系统 103 | 104 | **学习重点：** 作为日常参考手册，快速查找和应用Claude Code功能。 105 | 106 | --- 107 | 108 | ## 🚀 推荐学习路径 109 | 110 | ### 🌱 初学者路径 111 | 1. **第一章：核心概念和导航** → 理解基础 112 | 2. **第六章：快速参考** → 掌握基本命令 113 | 3. **第三章：开发工作流** → 学习基本开发流程 114 | 4. **第二章：集成系统** → 扩展功能使用 115 | 116 | ### 🎯 中级用户路径 117 | 1. **第四章：Meta-Todo系统** → 提升任务管理 118 | 2. **第三章：高级模式** → 掌握高级工作流 119 | 3. **第五章：高级协同** → 理解系统协同 120 | 4. **第一章：深度内容** → 巩固理论基础 121 | 122 | ### 🏆 高级用户路径 123 | 1. **第五章：高级协同实现** → 掌握最高级技术 124 | 2. **第四章：智能任务编排** → 优化项目流程 125 | 3. **第二章：深度集成** → 构建完整生态系统 126 | 4. **第六章：专家技巧** → 精通高级应用 127 | 128 | ## 🛠️ 实践建议 129 | 130 | ### 💡 学习方法 131 | - **循序渐进**：按推荐路径学习，建立坚实基础 132 | - **实践为主**：每个概念都要在项目中实际应用 133 | - **反复练习**：多次使用不同功能，掌握熟练度 134 | - **分享交流**：与团队分享学习心得，共同进步 135 | 136 | ### 📝 学习工具 137 | - **CLAUDE.md**：建立项目上下文，记录学习进度 138 | - **任务管理**：使用TodoWrite跟踪学习任务 139 | - **实验项目**：创建专门的练习项目 140 | - **笔记整理**：记录重要的概念和技巧 141 | 142 | ### 🔧 实践项目建议 143 | 1. **个人博客**：练习全栈开发 144 | 2. **工具应用**：构建实用工具 145 | 3. **API服务**：练习后端开发 146 | 4. **前端应用**：掌握UI/UX开发 147 | 5. **DevOps工具**：学习自动化和部署 148 | 149 | ## 📊 技能提升路径 150 | 151 | ### Level 1: 基础应用 (0-1个月) 152 | - [ ] 掌握基本命令和操作 153 | - [ ] 理解核心概念和架构 154 | - [ ] 能够完成简单开发任务 155 | - [ ] 建立基本的工作流程 156 | 157 | ### Level 2: 熟练应用 (1-3个月) 158 | - [ ] 熟练使用各种功能 159 | - [ ] 掌握项目管理和任务分解 160 | - [ ] 能够处理中等复杂度项目 161 | - [ ] 建立个人开发模式 162 | 163 | ### Level 3: 高级应用 (3-6个月) 164 | - [ ] 掌握高级协同和集成 165 | - [ ] 能够处理复杂项目架构 166 | - [ ] 建立完整的开发生态 167 | - [ ] 优化团队协作流程 168 | 169 | ### Level 4: 专家应用 (6个月+) 170 | - [ ] 精通所有功能和技术 171 | - [ ] 能够设计和优化开发系统 172 | - [ ] 指导团队成员学习和应用 173 | - [ ] 推动技术创新和改进 174 | 175 | ## 🤝 社区贡献 176 | 177 | ### 📝 贡献方式 178 | - **内容改进**：提出翻译改进建议 179 | - **实践案例**：分享使用经验和案例 180 | - **问题解答**：帮助其他学习者解决问题 181 | - **功能探索**：探索和分享新功能用法 182 | 183 | ### 📬 反馈渠道 184 | - **GitHub Issues**：报告问题和建议 185 | - **Pull Requests**：贡献内容改进 186 | - **讨论论坛**：参与技术讨论 187 | - **学习小组**：组织学习交流活动 188 | 189 | ## 📈 学习效果评估 190 | 191 | ### 🎯 评估指标 192 | - **开发效率**：完成任务的时间和速度 193 | - **代码质量**：产出代码的质量和可维护性 194 | - **问题解决**：处理复杂问题的能力 195 | - **创新能力**：应用技术解决新问题的能力 196 | 197 | ### 📊 进度跟踪 198 | 使用以下工具跟踪学习进度： 199 | - **任务清单**：使用TodoWrite管理学习任务 200 | - **项目日志**：记录学习过程和心得 201 | - **技能矩阵**：评估技能掌握程度 202 | - **成果展示**：展示学习成果和项目 203 | 204 | ## 🔗 相关资源 205 | 206 | ### 📚 官方资源 207 | - [Claude Code 官方文档](https://docs.anthropic.com/claude/docs/claude-code) 208 | - [Claude API 文档](https://docs.anthropic.com/claude/docs) 209 | - [Anthropic 开发者门户](https://www.anthropic.com/developer) 210 | 211 | ### 🛠️ 工具和扩展 212 | - [MCP 服务器](https://github.com/modelcontextprotocol) 213 | - [Claude Code 扩展](https://github.com/topics/claude-code) 214 | - [开发工具集成](https://github.com/topics/claude-integration) 215 | 216 | ### 🤝 社区资源 217 | - [Claude Code 讨论](https://github.com/anthropics/claude-code/discussions) 218 | - [开发者社区](https://stackoverflow.com/questions/tagged/claude-code) 219 | - [学习资源分享](https://github.com/topics/claude-learning) 220 | 221 | --- 222 | 223 | ## 🎓 结语 224 | 225 | Claude Code 不仅仅是一个开发工具，它代表了AI辅助开发的未来方向。通过本系列课程的学习，您将掌握如何与AI协作，建立更高效、更智能的开发流程。 226 | 227 | **记住**：技术不断演进，学习永无止境。保持好奇心，持续实践，探索更多可能性！ 228 | 229 | --- 230 | 231 | **翻译信息：** 232 | - **原始文档：** [Cranot/claude-code-guide](https://github.com/Cranot/claude-code-guide) 233 | - **文档规模：** 约9,586行，339KB 234 | - **翻译范围：** 完整中文翻译，分章节组织 235 | - **更新时间：** 2025年9月 236 | 237 | **使用说明：** 238 | 1. 按推荐路径循序渐进学习 239 | 2. 每个章节都要进行实践操作 240 | 3. 在实际项目中应用所学知识 241 | 4. 与社区交流分享学习心得 242 | 243 | **祝您学习愉快，开发高效！** 🚀 -------------------------------------------------------------------------------- /docs/README.md: -------------------------------------------------------------------------------- 1 | # Documentation System Guide 2 | 3 | This guide explains how the 3-tier documentation architecture powers the Claude Code Development Kit and why it provides superior results compared to traditional documentation approaches. 4 | 5 | ## Critical Foundation Files 6 | 7 | Two files form the cornerstone of the entire documentation system: 8 | 9 | 1. **docs-overview.md** - The central routing guide that directs AI agents to appropriate documentation based on task complexity. This file maps your entire documentation structure and enables intelligent context loading. 10 | 11 | 2. **project-structure.md** - The comprehensive overview of your project's complete file structure and technology stack. This file is required reading for all AI agents and must be attached to Gemini consultations. 12 | 13 | These foundation files ensure AI agents always have the essential context needed to understand your project and navigate to relevant documentation. 14 | 15 | ## Why the 3-Tier System 16 | 17 | ### Traditional Documentation Problems 18 | 19 | Standard documentation approaches create friction for AI-assisted development: 20 | 21 | - **Context Overload** - AI agents must process entire documentation sets for simple tasks 22 | - **Maintenance Burden** - Every code change cascades to multiple documentation locations 23 | - **Stale Content** - Documentation diverges from implementation reality 24 | - **No AI Optimization** - Human-readable formats lack structure for machine processing 25 | 26 | ### The 3-Tier Solution 27 | 28 | The kit solves these problems through hierarchical organization: 29 | 30 | **Tier 1: Foundation (Rarely Changes)** 31 | - Project-wide standards, architecture decisions, technology stack 32 | - Auto-loads for every AI session 33 | - Provides consistent baseline without redundancy 34 | - Uses CLAUDE.md as the master context file 35 | 36 | **Tier 2: Component (Occasionally Changes)** 37 | - Component boundaries, architectural patterns, integration points 38 | - Loads only when working within specific components 39 | - Isolates architectural decisions from implementation details 40 | - Uses CONTEXT.md files at component roots 41 | 42 | **Tier 3: Feature (Frequently Changes)** 43 | - Implementation specifics, technical details, local patterns 44 | - Co-located with code for immediate updates 45 | - Minimizes documentation cascade when code changes 46 | - Uses CONTEXT.md files within feature directories 47 | 48 | ## Benefits vs Traditional Systems 49 | 50 | ### 1. Intelligent Context Loading 51 | 52 | **Traditional**: AI loads entire documentation corpus regardless of task 53 | **3-Tier**: Commands load only relevant tiers based on complexity 54 | 55 | Example: 56 | - Simple query → Tier 1 only (minimal tokens) 57 | - Component work → Tier 1 + relevant Tier 2 58 | - Deep implementation → All relevant tiers 59 | 60 | ### 2. Maintenance Efficiency 61 | 62 | **Traditional**: Update multiple documents for each change 63 | **3-Tier**: Updates isolated to appropriate tier 64 | 65 | Example: 66 | - API endpoint change → Update only Tier 3 API documentation 67 | - New component → Add Tier 2 documentation, Tier 1 unchanged 68 | - Coding standard → Update only Tier 1, applies everywhere 69 | 70 | ### 3. AI Performance Optimization 71 | 72 | **Traditional**: AI struggles to find relevant information 73 | **3-Tier**: Structured hierarchy guides AI to precise context 74 | 75 | The system provides: 76 | - Clear routing logic for agent navigation 77 | - Predictable documentation locations 78 | - Efficient token usage through targeted loading 79 | 80 | ## Integration with Kit Components 81 | 82 | ### Command Integration 83 | 84 | Commands leverage the 3-tier structure for intelligent operation: 85 | 86 | ``` 87 | Command Execution → Analyze Task Complexity → Load Appropriate Tiers 88 | ↓ 89 | Simple: Tier 1 only 90 | Component: Tiers 1-2 91 | Complex: All relevant tiers 92 | ``` 93 | 94 | ### MCP Server Integration 95 | 96 | External AI services receive proper context through the tier system: 97 | 98 | - **Gemini Consultations** - Auto-attach `project-structure.md` (Tier 1) 99 | - **Context7 Lookups** - Happen within established project context 100 | - **Recommendations** - Align with documented architecture 101 | 102 | ### Multi-Agent Routing 103 | 104 | The documentation structure determines agent behavior: 105 | 106 | - Number of agents spawned based on tiers involved 107 | - Each agent receives targeted documentation subset 108 | - Parallel analysis without context overlap 109 | 110 | ## Key Files and Their Roles 111 | 112 | ### Foundation Files (ai-context/) 113 | 114 | **docs-overview.md** 115 | - Template for implementing 3-tier documentation 116 | - Maps documentation structure for AI navigation 117 | - [View Template](ai-context/docs-overview.md) 118 | 119 | **project-structure.md** 120 | - Complete technology stack and file organization 121 | - Required reading for all AI agents 122 | - Auto-attaches to Gemini consultations 123 | - [View Template](ai-context/project-structure.md) 124 | 125 | **system-integration.md** 126 | - Cross-component communication patterns 127 | - Integration architectures for multi-agent analysis 128 | - [View Template](ai-context/system-integration.md) 129 | 130 | **deployment-infrastructure.md** 131 | - Infrastructure patterns and constraints 132 | - Deployment context for AI recommendations 133 | - [View Template](ai-context/deployment-infrastructure.md) 134 | 135 | **handoff.md** 136 | - Session continuity between AI interactions 137 | - Task state preservation 138 | - [View Template](ai-context/handoff.md) 139 | 140 | ### Context Templates 141 | 142 | **CLAUDE.md** (Tier 1) 143 | - Master AI context with coding standards 144 | - Project-wide instructions and patterns 145 | - [View Template](CLAUDE.md) 146 | 147 | **CONTEXT-tier2-component.md** 148 | - Component-level architectural context 149 | - [View Template](CONTEXT-tier2-component.md) 150 | 151 | **CONTEXT-tier3-feature.md** 152 | - Feature-specific implementation details 153 | - [View Template](CONTEXT-tier3-feature.md) 154 | 155 | ## Implementation Strategy 156 | 157 | ### 1. Start with Templates 158 | 159 | Use provided templates as foundation: 160 | - Copy and customize for your project 161 | - Maintain consistent structure 162 | - Focus on AI-consumable formatting 163 | 164 | ### 2. Follow Natural Boundaries 165 | 166 | Let your architecture guide tier placement: 167 | - Stable decisions → Tier 1 168 | - Component design → Tier 2 169 | - Implementation details → Tier 3 170 | 171 | ### 3. Co-locate Documentation 172 | 173 | Place CONTEXT.md files with related code: 174 | ``` 175 | backend/ 176 | ├── CONTEXT.md # Backend architecture (Tier 2) 177 | └── src/ 178 | └── api/ 179 | └── CONTEXT.md # API implementation (Tier 3) 180 | ``` 181 | 182 | ### 4. Maintain Hierarchy 183 | 184 | Ensure clear relationships: 185 | - Tier 3 references Tier 2 patterns 186 | - Tier 2 follows Tier 1 standards 187 | - No circular dependencies 188 | 189 | ### 5. Use Documentation Commands 190 | 191 | The kit provides commands to manage documentation: 192 | - **`/create-docs`** - Generate initial documentation structure for projects without existing docs 193 | - **`/update-docs`** - Regenerate and update documentation after code changes to keep everything current 194 | 195 | ## Measuring Success 196 | 197 | The 3-tier system succeeds when: 198 | 199 | 1. **AI agents find context quickly** - No searching through irrelevant documentation 200 | 2. **Updates stay localized** - Changes don't cascade unnecessarily 201 | 3. **Documentation stays current** - Co-location ensures updates happen 202 | 4. **Commands work efficiently** - Appropriate context loads automatically 203 | 5. **MCP servers provide relevant advice** - External AI understands your project 204 | 205 | --- 206 | 207 | *Part of the Claude Code Development Kit - see [main documentation](../README.md) for complete system overview.* -------------------------------------------------------------------------------- /docs/ai-context/deployment-infrastructure.md: -------------------------------------------------------------------------------- 1 | # Deployment & Infrastructure Documentation 2 | 3 | This document contains deployment and infrastructure-related documentation for the project. 4 | 5 | ## Purpose 6 | 7 | This template serves as a placeholder for documenting: 8 | - Deployment strategies and procedures 9 | - Infrastructure architecture and configuration 10 | - CI/CD pipelines and automation 11 | - Environment management 12 | - Monitoring and observability setup 13 | - Scaling strategies and considerations 14 | 15 | ## Implementation Note 16 | 17 | Replace this template with your actual deployment and infrastructure documentation as your project develops. Focus on patterns and decisions that AI agents need to understand when working with infrastructure-related code or making architectural recommendations. 18 | 19 | --- 20 | 21 | *Customize this template based on your specific deployment and infrastructure requirements.* -------------------------------------------------------------------------------- /docs/ai-context/docs-overview.md: -------------------------------------------------------------------------------- 1 | # Documentation Architecture 2 | 3 | This project uses a **3-tier documentation system** that organizes knowledge by stability and scope, enabling efficient AI context loading and scalable development. 4 | 5 | ## How the 3-Tier System Works 6 | 7 | **Tier 1 (Foundation)**: Stable, system-wide documentation that rarely changes - architectural principles, technology decisions, cross-component patterns, and core development protocols. 8 | 9 | **Tier 2 (Component)**: Architectural charters for major components - high-level design principles, integration patterns, and component-wide conventions without feature-specific details. 10 | 11 | **Tier 3 (Feature-Specific)**: Granular documentation co-located with code - specific implementation patterns, technical details, and local architectural decisions that evolve with features. 12 | 13 | This hierarchy allows AI agents to load targeted context efficiently while maintaining a stable foundation of core knowledge. 14 | 15 | ## Documentation Principles 16 | - **Co-location**: Documentation lives near relevant code 17 | - **Smart Extension**: New documentation files created automatically when warranted 18 | - **AI-First**: Optimized for efficient AI context loading and machine-readable patterns 19 | 20 | ## Tier 1: Foundational Documentation (System-Wide) 21 | 22 | - **[Master Context](/CLAUDE.md)** - *Essential for every session.* Coding standards, security requirements, MCP server integration patterns, and development protocols 23 | - **[Project Structure](/docs/ai-context/project-structure.md)** - *REQUIRED reading.* Complete technology stack, file tree, and system architecture. Must be attached to Gemini consultations 24 | - **[System Integration](/docs/ai-context/system-integration.md)** - *For cross-component work.* Communication patterns, data flow, testing strategies, and performance optimization 25 | - **[Deployment Infrastructure](/docs/ai-context/deployment-infrastructure.md)** - *Infrastructure patterns.* Containerization, monitoring, CI/CD workflows, and scaling strategies 26 | - **[Task Management](/docs/ai-context/handoff.md)** - *Session continuity.* Current tasks, documentation system progress, and next session goals 27 | 28 | ## Tier 2: Component-Level Documentation 29 | 30 | ### Backend Components 31 | - **[Backend Context](/backend/CONTEXT.md)** - *Server implementation.* API patterns, database integration, service architecture, and performance considerations 32 | - **[Worker Services](/workers/CONTEXT.md)** - *Background processing.* Job queue patterns, scheduling, and async task management 33 | - **[Shared Libraries](/shared/CONTEXT.md)** - *Reusable code.* Common utilities, shared types, and cross-component functionality 34 | 35 | ### Frontend Components 36 | - **[Web Application](/frontend/CONTEXT.md)** - *Client implementation.* UI patterns, state management, routing, and user interaction patterns 37 | - **[Mobile Application](/mobile/CONTEXT.md)** - *Mobile implementation.* Platform-specific patterns, native integrations, and mobile optimizations 38 | - **[Admin Dashboard](/admin/CONTEXT.md)** - *Administrative interface.* Permission patterns, admin workflows, and management tools 39 | 40 | ### Infrastructure Components 41 | - **[Infrastructure Code](/infrastructure/CONTEXT.md)** - *IaC patterns.* Terraform/CloudFormation templates, resource definitions, and deployment automation 42 | - **[Monitoring Setup](/monitoring/CONTEXT.md)** - *Observability patterns.* Metrics collection, alerting rules, and dashboard configurations 43 | 44 | ## Tier 3: Feature-Specific Documentation 45 | 46 | Granular CONTEXT.md files co-located with code for minimal cascade effects: 47 | 48 | ### Backend Feature Documentation 49 | - **[Core Services](/backend/src/core/services/CONTEXT.md)** - *Business logic patterns.* Service architecture, data processing, integration patterns, and error handling 50 | - **[API Layer](/backend/src/api/CONTEXT.md)** - *API patterns.* Endpoint design, validation, middleware, and request/response handling 51 | - **[Data Layer](/backend/src/data/CONTEXT.md)** - *Data patterns.* Database models, queries, migrations, and data access patterns 52 | - **[Authentication](/backend/src/auth/CONTEXT.md)** - *Auth patterns.* Authentication flows, authorization rules, session management, and security 53 | - **[Integrations](/backend/src/integrations/CONTEXT.md)** - *External services.* Third-party API clients, webhook handlers, and service adapters 54 | 55 | ### Frontend Feature Documentation 56 | - **[UI Components](/frontend/src/components/CONTEXT.md)** - *Component patterns.* Reusable components, styling patterns, accessibility, and composition strategies 57 | - **[State Management](/frontend/src/store/CONTEXT.md)** - *State patterns.* Global state, local state, data flow, and persistence strategies 58 | - **[API Client](/frontend/src/api/CONTEXT.md)** - *Client patterns.* HTTP clients, error handling, caching, and data synchronization 59 | - **[Routing](/frontend/src/routes/CONTEXT.md)** - *Navigation patterns.* Route definitions, guards, lazy loading, and deep linking 60 | - **[Utilities](/frontend/src/utils/CONTEXT.md)** - *Helper functions.* Formatters, validators, transformers, and common utilities 61 | 62 | ### Shared Feature Documentation 63 | - **[Common Types](/shared/src/types/CONTEXT.md)** - *Type definitions.* Shared interfaces, enums, and type utilities 64 | - **[Validation Rules](/shared/src/validation/CONTEXT.md)** - *Validation patterns.* Schema definitions, custom validators, and error messages 65 | - **[Constants](/shared/src/constants/CONTEXT.md)** - *Shared constants.* Configuration values, enums, and magic numbers 66 | - **[Utilities](/shared/src/utils/CONTEXT.md)** - *Shared utilities.* Cross-platform helpers, formatters, and common functions 67 | 68 | 69 | 70 | ## Adding New Documentation 71 | 72 | ### New Component 73 | 1. Create `/new-component/CONTEXT.md` (Tier 2) 74 | 2. Add entry to this file under appropriate section 75 | 3. Create feature-specific Tier 3 docs as features develop 76 | 77 | ### New Feature 78 | 1. Create `/component/src/feature/CONTEXT.md` (Tier 3) 79 | 2. Reference parent component patterns 80 | 3. Add entry to this file under component's features 81 | 82 | ### Deprecating Documentation 83 | 1. Remove obsolete CONTEXT.md files 84 | 2. Update this mapping document 85 | 3. Check for broken references in other docs 86 | 87 | --- 88 | 89 | *This documentation architecture template should be customized to match your project's actual structure and components. Add or remove sections based on your architecture.* -------------------------------------------------------------------------------- /docs/ai-context/handoff.md: -------------------------------------------------------------------------------- 1 | # Task Management & Handoff Template 2 | 3 | This file manages task continuity, session transitions, and knowledge transfer for AI-assisted development sessions. 4 | 5 | ## Purpose 6 | 7 | This template helps maintain: 8 | - **Session continuity** between AI development sessions 9 | - **Task status tracking** for complex, multi-session work 10 | - **Context preservation** when switching between team members 11 | - **Knowledge transfer** for project handoffs 12 | - **Progress documentation** for ongoing development efforts 13 | 14 | ## Current Session Status 15 | 16 | ### Active Tasks 17 | Document currently in-progress work: 18 | 19 | ```markdown 20 | ## In Progress 21 | - [ ] Task 1: [Brief description] 22 | - Status: [Started/Blocked/Awaiting review] 23 | - Context: [Relevant files, decisions made] 24 | - Next steps: [What needs to be done next] 25 | - Dependencies: [What this task depends on] 26 | 27 | - [ ] Task 2: [Brief description] 28 | - Status: [Current status] 29 | - Files modified: [List of files changed] 30 | - Challenges: [Any issues encountered] 31 | - Notes: [Important context for continuation] 32 | ``` 33 | 34 | ### Pending Tasks 35 | Document queued work: 36 | 37 | ```markdown 38 | ## Pending 39 | - [ ] Task A: [Description] 40 | - Priority: [High/Medium/Low] 41 | - Dependencies: [What must be completed first] 42 | - Estimated effort: [Time estimate] 43 | - Context: [Background information] 44 | 45 | - [ ] Task B: [Description] 46 | - Priority: [Priority level] 47 | - Requirements: [Specific requirements or constraints] 48 | - Resources needed: [Tools, access, information needed] 49 | ``` 50 | 51 | ### Completed Tasks 52 | Track completed work for context: 53 | 54 | ```markdown 55 | ## Completed This Session 56 | - [x] Task X: [Description] 57 | - Completed: [Date] 58 | - Outcome: [What was accomplished] 59 | - Files changed: [Modified files] 60 | - Notes: [Important decisions or lessons learned] 61 | 62 | - [x] Task Y: [Description] 63 | - Completed: [Date] 64 | - Impact: [How this affects other tasks] 65 | - Follow-up needed: [Any follow-up actions required] 66 | ``` 67 | 68 | ## Architecture & Design Decisions 69 | 70 | ### Recent Decisions 71 | Document architectural decisions made during development: 72 | 73 | ```markdown 74 | ## Design Decisions Made 75 | - **Decision**: [What was decided] 76 | - Date: [When decision was made] 77 | - Rationale: [Why this approach was chosen] 78 | - Alternatives considered: [Other options evaluated] 79 | - Impact: [How this affects the system] 80 | - Validation: [How to verify this was the right choice] 81 | 82 | - **Decision**: [Another decision] 83 | - Context: [Situation that led to this decision] 84 | - Trade-offs: [What was gained/lost with this choice] 85 | - Dependencies: [What this decision depends on] 86 | ``` 87 | 88 | ### Technical Debt & Issues 89 | Track technical debt and known issues: 90 | 91 | ```markdown 92 | ## Technical Debt Identified 93 | - **Issue**: [Description of technical debt] 94 | - Location: [Where in codebase] 95 | - Impact: [How it affects development/performance] 96 | - Proposed solution: [How to address it] 97 | - Priority: [When should this be addressed] 98 | 99 | - **Issue**: [Another issue] 100 | - Root cause: [Why this debt exists] 101 | - Workaround: [Current mitigation strategy] 102 | - Long-term fix: [Proper solution approach] 103 | ``` 104 | 105 | ## Next Session Goals 106 | 107 | ### Immediate Priorities 108 | Define what should be tackled next: 109 | 110 | ```markdown 111 | ## Next Session Priorities 112 | 1. **Primary Goal**: [Main objective for next session] 113 | - Success criteria: [How to know this is complete] 114 | - Prerequisites: [What must be ready beforehand] 115 | - Estimated effort: [Time estimate] 116 | 117 | 2. **Secondary Goal**: [Secondary objective] 118 | - Dependencies: [What this depends on] 119 | - Resources needed: [Tools, information, access required] 120 | 121 | 3. **If Time Permits**: [Optional tasks] 122 | - Context: [Background on why these are valuable] 123 | - Preparation: [What needs to be done to start these] 124 | ``` 125 | 126 | ### Knowledge Gaps 127 | Document areas needing research or clarification: 128 | 129 | ```markdown 130 | ## Knowledge Gaps to Address 131 | - **Question**: [What needs to be clarified] 132 | - Impact: [How this affects current work] 133 | - Research needed: [What investigation is required] 134 | - Decision maker: [Who can answer this] 135 | 136 | - **Unknown**: [Technical uncertainty] 137 | - Options: [Possible approaches to explore] 138 | - Experiments: [What should be tested] 139 | - Timeline: [When this needs to be resolved] 140 | ``` 141 | 142 | ## Context for Continuation 143 | 144 | ### Key Files & Components 145 | Document important files for session continuity: 146 | 147 | ```markdown 148 | ## Files Currently Being Modified 149 | - `[file-path]`: [Purpose and current changes] 150 | - `[file-path]`: [What's being implemented here] 151 | - `[file-path]`: [Status and next steps] 152 | 153 | ## Important Context Files 154 | - `[context-file]`: [Why this is relevant] 155 | - `[documentation]`: [What information this contains] 156 | - `[reference]`: [How this relates to current work] 157 | ``` 158 | 159 | ### Development Environment 160 | Document environment and setup considerations: 161 | 162 | ```markdown 163 | ## Environment Status 164 | - **Development setup**: [Current state of dev environment] 165 | - **Database**: [Schema changes, migrations, data state] 166 | - **External services**: [API keys, service configurations] 167 | - **Testing**: [Test suite status, coverage, failing tests] 168 | - **Build/Deploy**: [Build status, deployment considerations] 169 | ``` 170 | 171 | 172 | --- 173 | 174 | *This template provides a comprehensive framework for managing task continuity and knowledge transfer. Customize it based on your team's workflow, project complexity, and communication needs.* -------------------------------------------------------------------------------- /docs/ai-context/project-structure.md: -------------------------------------------------------------------------------- 1 | # Project Structure Template 2 | 3 | This document provides a template for documenting the complete technology stack and file tree structure for your project. **AI agents MUST read this file to understand the project organization before making any changes.** 4 | 5 | ## Technology Stack Template 6 | 7 | ### Backend Technologies 8 | Document your backend technology choices: 9 | - **[Language] [Version]** with **[Package Manager]** - Dependency management and packaging 10 | - **[Web Framework] [Version]** - Web framework with specific features (async, type hints, etc.) 11 | - **[Server] [Version]** - Application server configuration 12 | - **[Configuration] [Version]** - Configuration management approach 13 | 14 | Example: 15 | ``` 16 | - Python 3.11+ with Poetry - Dependency management and packaging 17 | - FastAPI 0.115.0+ - Web framework with type hints and async support 18 | - Uvicorn 0.32.0+ - ASGI server with standard extras 19 | - Pydantic Settings 2.5.2+ - Configuration management with type validation 20 | ``` 21 | 22 | ### Integration Services & APIs 23 | Document external services and integrations: 24 | - **[Service Name] [API/SDK Version]** - Purpose and usage pattern 25 | - **[AI Service] [Version]** - AI/ML service integration details 26 | - **[Database] [Version]** - Data storage and management 27 | - **[Monitoring] [Version]** - Observability and logging 28 | 29 | ### Real-time Communication 30 | Document real-time features: 31 | - **[WebSocket Library]** - Real-time communication patterns 32 | - **[HTTP Client]** - Async HTTP communication 33 | - **[Message Queue]** - Event processing (if applicable) 34 | 35 | ### Development & Quality Tools 36 | Document development toolchain: 37 | - **[Formatter] [Version]** - Code formatting 38 | - **[Linter] [Version]** - Code quality and linting 39 | - **[Type Checker] [Version]** - Static type checking 40 | - **[Testing Framework] [Version]** - Testing approach 41 | - **[Task Runner]** - Build automation and task orchestration 42 | 43 | ### Frontend Technologies (if applicable) 44 | Document frontend technology stack: 45 | - **[Language] [Version]** - Frontend development language 46 | - **[Framework] [Version]** - UI framework 47 | - **[Build Tool] [Version]** - Development and build tooling 48 | - **[Deployment] [Version]** - Deployment and hosting approach 49 | 50 | ### Future Technologies 51 | Document planned technology additions: 52 | - **[Planned Technology]** - Future integration plans 53 | - **[Platform]** - Target platform expansion 54 | - **[Service]** - Planned service integrations 55 | 56 | ## Complete Project Structure Template 57 | 58 | ``` 59 | [PROJECT-NAME]/ 60 | ├── README.md # Project overview and setup 61 | ├── CLAUDE.md # Master AI context file 62 | ├── [BUILD-FILE] # Build configuration (Makefile, package.json, etc.) 63 | ├── .gitignore # Git ignore patterns 64 | ├── .[IDE-CONFIG]/ # IDE workspace configuration 65 | │ ├── settings.[ext] # IDE settings 66 | │ ├── extensions.[ext] # Recommended extensions 67 | │ └── launch.[ext] # Debug configurations 68 | ├── [BACKEND-DIR]/ # Backend application 69 | │ ├── CONTEXT.md # Backend-specific AI context 70 | │ ├── src/ # Source code 71 | │ │ ├── config/ # Configuration management 72 | │ │ │ └── settings.[ext] # Application settings 73 | │ │ ├── core/ # Core business logic 74 | │ │ │ ├── CONTEXT.md # Core logic patterns 75 | │ │ │ ├── services/ # Business services 76 | │ │ │ │ ├── [service1].[ext] # Service implementations 77 | │ │ │ │ └── [service2].[ext] 78 | │ │ │ ├── models/ # Data models 79 | │ │ │ │ ├── [model1].[ext] # Model definitions 80 | │ │ │ │ └── [model2].[ext] 81 | │ │ │ └── utils/ # Utility functions 82 | │ │ │ ├── logging.[ext] # Structured logging 83 | │ │ │ ├── validation.[ext] # Input validation 84 | │ │ │ └── helpers.[ext] # Helper functions 85 | │ │ ├── api/ # API layer 86 | │ │ │ ├── CONTEXT.md # API patterns and conventions 87 | │ │ │ ├── routes/ # API route definitions 88 | │ │ │ │ ├── [resource1].[ext] # Resource-specific routes 89 | │ │ │ │ └── [resource2].[ext] 90 | │ │ │ ├── middleware/ # API middleware 91 | │ │ │ │ ├── auth.[ext] # Authentication middleware 92 | │ │ │ │ ├── logging.[ext] # Request logging 93 | │ │ │ │ └── validation.[ext] # Request validation 94 | │ │ │ └── schemas/ # Request/response schemas 95 | │ │ │ ├── [schema1].[ext] # Data schemas 96 | │ │ │ └── [schema2].[ext] 97 | │ │ └── integrations/ # External service integrations 98 | │ │ ├── CONTEXT.md # Integration patterns 99 | │ │ ├── [service1]/ # Service-specific integration 100 | │ │ │ ├── client.[ext] # API client 101 | │ │ │ ├── models.[ext] # Integration models 102 | │ │ │ └── handlers.[ext] # Response handlers 103 | │ │ └── [service2]/ 104 | │ ├── tests/ # Test suite 105 | │ │ ├── unit/ # Unit tests 106 | │ │ ├── integration/ # Integration tests 107 | │ │ └── fixtures/ # Test fixtures and data 108 | │ ├── [PACKAGE-FILE] # Package configuration 109 | │ └── [ENV-FILE] # Environment configuration 110 | ├── [FRONTEND-DIR]/ # Frontend application (if applicable) 111 | │ ├── CONTEXT.md # Frontend-specific AI context 112 | │ ├── src/ # Source code 113 | │ │ ├── components/ # UI components 114 | │ │ │ ├── CONTEXT.md # Component patterns 115 | │ │ │ ├── common/ # Shared components 116 | │ │ │ └── [feature]/ # Feature-specific components 117 | │ │ ├── pages/ # Page components/routes 118 | │ │ │ ├── [page1].[ext] # Page implementations 119 | │ │ │ └── [page2].[ext] 120 | │ │ ├── stores/ # State management 121 | │ │ │ ├── CONTEXT.md # State management patterns 122 | │ │ │ ├── [store1].[ext] # Store implementations 123 | │ │ │ └── [store2].[ext] 124 | │ │ ├── api/ # API client layer 125 | │ │ │ ├── CONTEXT.md # Client patterns 126 | │ │ │ ├── client.[ext] # HTTP client setup 127 | │ │ │ └── endpoints/ # API endpoint definitions 128 | │ │ ├── utils/ # Utility functions 129 | │ │ │ ├── logging.[ext] # Client-side logging 130 | │ │ │ ├── validation.[ext] # Form validation 131 | │ │ │ └── helpers.[ext] # Helper functions 132 | │ │ └── assets/ # Static assets 133 | │ ├── tests/ # Frontend tests 134 | │ ├── [BUILD-CONFIG] # Build configuration 135 | │ └── [PACKAGE-FILE] # Package configuration 136 | ├── docs/ # Documentation 137 | │ ├── ai-context/ # AI-specific documentation 138 | │ │ ├── project-structure.md # This file 139 | │ │ ├── docs-overview.md # Documentation architecture 140 | │ │ ├── system-integration.md # Integration patterns 141 | │ │ ├── deployment-infrastructure.md # Infrastructure docs 142 | │ │ └── handoff.md # Task management 143 | │ ├── api/ # API documentation 144 | │ ├── deployment/ # Deployment guides 145 | │ └── development/ # Development guides 146 | ├── scripts/ # Automation scripts 147 | │ ├── setup.[ext] # Environment setup 148 | │ ├── deploy.[ext] # Deployment scripts 149 | │ └── maintenance/ # Maintenance scripts 150 | ├── [INFRASTRUCTURE-DIR]/ # Infrastructure as code (if applicable) 151 | │ ├── [PROVIDER]/ # Cloud provider configurations 152 | │ ├── docker/ # Container configurations 153 | │ └── monitoring/ # Monitoring and alerting 154 | └── [CONFIG-FILES] # Root-level configuration files 155 | ``` 156 | 157 | 158 | --- 159 | 160 | *This template provides a comprehensive foundation for documenting project structure. Adapt it based on your specific technology stack, architecture decisions, and organizational requirements.* -------------------------------------------------------------------------------- /docs/ai-context/system-integration.md: -------------------------------------------------------------------------------- 1 | # System Integration Documentation 2 | 3 | This document contains cross-component integration patterns and system-wide architectural decisions. 4 | 5 | ## Purpose 6 | 7 | This template serves as a placeholder for documenting: 8 | - Cross-component communication patterns 9 | - Data flow architectures between services 10 | - Integration strategies with external systems 11 | - Performance optimization patterns 12 | - Testing strategies for integrated systems 13 | - Error handling across service boundaries 14 | 15 | ## Implementation Note 16 | 17 | Replace this template with your actual system integration documentation as your project develops. Focus on patterns that AI agents need to understand when working across component boundaries or implementing features that span multiple services. 18 | 19 | --- 20 | 21 | *Customize this template based on your specific integration patterns and architectural requirements.* -------------------------------------------------------------------------------- /docs/open-issues/example-api-performance-issue.md: -------------------------------------------------------------------------------- 1 | # API Performance Issue - Example Template 2 | 3 | ## Issue Description 4 | 5 | Describe the specific performance issue or bug that needs to be addressed. Include symptoms, affected features, and user impact. 6 | 7 | Example: "API endpoint `/api/data/process` has intermittent high latency (>5 seconds) under normal load conditions, causing user timeout errors." 8 | 9 | ## Root Cause 10 | 11 | Detailed analysis of what's causing the issue. Include: 12 | - Technical root cause 13 | - Contributing factors 14 | - System conditions that trigger the issue 15 | 16 | Example: "Database query optimization needed for complex joins. Current query scans entire table without proper indexing." 17 | 18 | ## Impact Assessment 19 | 20 | - **Severity**: Critical/High/Medium/Low 21 | - **Affected Users**: Percentage or number of users impacted 22 | - **Business Impact**: Revenue, user experience, or operational impact 23 | - **Workarounds**: Any temporary solutions currently in place 24 | 25 | ## Proposed Solution 26 | 27 | ### Technical Approach 28 | Detailed technical solution including: 29 | - Code changes required 30 | - Architecture modifications 31 | - Database schema updates 32 | - Performance improvements expected 33 | 34 | ### Implementation Plan 35 | 1. **Phase 1**: Initial fixes (timeline) 36 | 2. **Phase 2**: Optimization improvements (timeline) 37 | 3. **Phase 3**: Monitoring and validation (timeline) 38 | 39 | ## Testing Strategy 40 | 41 | - **Unit Tests**: Specific test cases to validate the fix 42 | - **Integration Tests**: End-to-end testing scenarios 43 | - **Performance Tests**: Load testing and benchmarking 44 | - **Regression Tests**: Ensure no existing functionality breaks 45 | 46 | ## Related Files 47 | 48 | List all files that need to be modified: 49 | - `src/api/routes/data.py` - Main endpoint logic 50 | - `src/database/models.py` - Database model updates 51 | - `src/utils/query_optimizer.py` - Query optimization utilities 52 | - `tests/test_api_performance.py` - Performance test suite 53 | 54 | ## References 55 | 56 | - [External documentation or APIs] 57 | - [Related GitHub issues or PRs] 58 | - [Performance benchmarking results] 59 | - [Stack Overflow discussions or solutions] 60 | 61 | ## Status 62 | 63 | - [ ] **Open** - Issue identified and documented 64 | - [ ] **In Progress** - Solution being implemented 65 | - [ ] **Testing** - Fix implemented, undergoing testing 66 | - [ ] **Fixed** - Issue resolved and deployed 67 | - [ ] **Closed** - Issue confirmed resolved in production 68 | 69 | ## Implementation Notes 70 | 71 | Track progress and implementation details: 72 | - Date started: [DATE] 73 | - Key decisions made: [DECISIONS] 74 | - Challenges encountered: [CHALLENGES] 75 | - Performance improvements achieved: [METRICS] 76 | 77 | --- 78 | 79 | *This template provides a structured approach to documenting and tracking technical issues. Customize sections based on your project's specific needs and workflow.* -------------------------------------------------------------------------------- /docs/specs/example-feature-specification.md: -------------------------------------------------------------------------------- 1 | # Feature Specification: Example Authentication System 2 | 3 | ## Overview 4 | 5 | This document outlines the implementation of a user authentication system for the application. This serves as a template for documenting feature specifications. 6 | 7 | ### Objectives 8 | - Implement secure user authentication 9 | - Support multiple authentication methods 10 | - Ensure scalable session management 11 | - Maintain security best practices 12 | 13 | ### Key Technologies 14 | - **Backend**: FastAPI with JWT tokens 15 | - **Database**: PostgreSQL with user management 16 | - **Frontend**: React/Svelte with secure token storage 17 | - **Security**: bcrypt for password hashing, OAuth2 for third-party auth 18 | 19 | ## Architecture 20 | 21 | ### Data Flow 22 | ``` 23 | User Registration → Input Validation → Password Hashing → Database Storage → JWT Token Generation → Client Storage 24 | ``` 25 | 26 | ### Authentication Flow 27 | ``` 28 | Login Request → Credential Validation → Database Lookup → Password Verification → JWT Token → Secure Cookie/Storage 29 | ``` 30 | 31 | ## Technical Specifications 32 | 33 | ### 1. Database Schema 34 | 35 | #### Users Table 36 | ```sql 37 | CREATE TABLE users ( 38 | id SERIAL PRIMARY KEY, 39 | email VARCHAR(255) UNIQUE NOT NULL, 40 | password_hash VARCHAR(255) NOT NULL, 41 | first_name VARCHAR(100), 42 | last_name VARCHAR(100), 43 | is_active BOOLEAN DEFAULT TRUE, 44 | created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, 45 | updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP 46 | ); 47 | ``` 48 | 49 | #### Sessions Table 50 | ```sql 51 | CREATE TABLE user_sessions ( 52 | id SERIAL PRIMARY KEY, 53 | user_id INTEGER REFERENCES users(id), 54 | session_token VARCHAR(255) UNIQUE NOT NULL, 55 | expires_at TIMESTAMP NOT NULL, 56 | created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP 57 | ); 58 | ``` 59 | 60 | ### 2. API Endpoints 61 | 62 | #### Authentication Endpoints 63 | - `POST /auth/register` - User registration 64 | - `POST /auth/login` - User login 65 | - `POST /auth/logout` - User logout 66 | - `POST /auth/refresh` - Token refresh 67 | - `GET /auth/me` - Get current user profile 68 | 69 | #### User Management Endpoints 70 | - `GET /users/profile` - Get user profile 71 | - `PUT /users/profile` - Update user profile 72 | - `DELETE /users/account` - Delete user account 73 | 74 | ### 3. Security Requirements 75 | 76 | #### Password Security 77 | - Minimum 8 characters 78 | - Must include uppercase, lowercase, number, and special character 79 | - Hashed using bcrypt with salt rounds >= 12 80 | 81 | #### Token Security 82 | - JWT tokens with 15-minute expiration 83 | - Refresh tokens with 7-day expiration 84 | - Secure HTTP-only cookies for token storage 85 | - CSRF protection for state-changing operations 86 | 87 | #### Rate Limiting 88 | - Login attempts: 5 per minute per IP 89 | - Registration: 3 per minute per IP 90 | - Password reset: 1 per minute per email 91 | 92 | ## Implementation Plan 93 | 94 | ### Phase 1: Core Authentication (Week 1) 95 | - [ ] Database schema setup 96 | - [ ] User registration endpoint 97 | - [ ] Login/logout endpoints 98 | - [ ] JWT token generation and validation 99 | - [ ] Basic password hashing 100 | 101 | ### Phase 2: Security Enhancements (Week 2) 102 | - [ ] Rate limiting implementation 103 | - [ ] CSRF protection 104 | - [ ] Session management 105 | - [ ] Password strength validation 106 | - [ ] Account lockout after failed attempts 107 | 108 | ### Phase 3: Advanced Features (Week 3) 109 | - [ ] OAuth2 integration (Google, GitHub) 110 | - [ ] Two-factor authentication 111 | - [ ] Password reset functionality 112 | - [ ] Email verification 113 | - [ ] Account recovery 114 | 115 | ### Phase 4: Testing & Deployment (Week 4) 116 | - [ ] Unit tests for all endpoints 117 | - [ ] Integration tests for auth flows 118 | - [ ] Security testing and penetration testing 119 | - [ ] Performance testing 120 | - [ ] Production deployment 121 | 122 | ## API Documentation 123 | 124 | ### Registration Endpoint 125 | ```http 126 | POST /auth/register 127 | Content-Type: application/json 128 | 129 | { 130 | "email": "user@example.com", 131 | "password": "SecurePass123!", 132 | "first_name": "John", 133 | "last_name": "Doe" 134 | } 135 | ``` 136 | 137 | **Response:** 138 | ```json 139 | { 140 | "success": true, 141 | "user": { 142 | "id": 1, 143 | "email": "user@example.com", 144 | "first_name": "John", 145 | "last_name": "Doe" 146 | }, 147 | "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...", 148 | "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..." 149 | } 150 | ``` 151 | 152 | ### Login Endpoint 153 | ```http 154 | POST /auth/login 155 | Content-Type: application/json 156 | 157 | { 158 | "email": "user@example.com", 159 | "password": "SecurePass123!" 160 | } 161 | ``` 162 | 163 | **Response:** 164 | ```json 165 | { 166 | "success": true, 167 | "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...", 168 | "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..." 169 | } 170 | ``` 171 | 172 | ## Testing Strategy 173 | 174 | ### Unit Tests 175 | - Password hashing and verification 176 | - JWT token generation and validation 177 | - Input validation and sanitization 178 | - Database operations 179 | 180 | ### Integration Tests 181 | - Complete authentication flows 182 | - Session management 183 | - Rate limiting functionality 184 | - CSRF protection 185 | 186 | ### Security Tests 187 | - SQL injection prevention 188 | - XSS protection 189 | - CSRF protection 190 | - Password strength validation 191 | - Rate limiting effectiveness 192 | 193 | ## Deployment Considerations 194 | 195 | ### Environment Variables 196 | ```bash 197 | # Database 198 | DATABASE_URL=postgresql://user:pass@localhost/dbname 199 | 200 | # JWT Configuration 201 | JWT_SECRET_KEY=your-secret-key 202 | JWT_ALGORITHM=HS256 203 | JWT_ACCESS_TOKEN_EXPIRE_MINUTES=15 204 | JWT_REFRESH_TOKEN_EXPIRE_DAYS=7 205 | 206 | # Rate Limiting 207 | RATE_LIMIT_ENABLED=true 208 | REDIS_URL=redis://localhost:6379 209 | 210 | # Email Configuration 211 | SMTP_SERVER=smtp.gmail.com 212 | SMTP_PORT=587 213 | SMTP_USERNAME=your-email@gmail.com 214 | SMTP_PASSWORD=your-app-password 215 | ``` 216 | 217 | ### Database Migrations 218 | ```bash 219 | # Create migration 220 | alembic revision --autogenerate -m "Add user authentication tables" 221 | 222 | # Apply migration 223 | alembic upgrade head 224 | ``` 225 | 226 | ## Performance Considerations 227 | 228 | ### Database Optimization 229 | - Index on email field for fast user lookups 230 | - Index on session_token for session validation 231 | - Regular cleanup of expired sessions 232 | 233 | ### Caching Strategy 234 | - Cache user profiles in Redis 235 | - Cache JWT blacklist for logout 236 | - Cache rate limiting counters 237 | 238 | ### Monitoring 239 | - Track authentication success/failure rates 240 | - Monitor session creation and cleanup 241 | - Alert on unusual login patterns 242 | 243 | ## Security Compliance 244 | 245 | ### OWASP Guidelines 246 | - Secure password storage (bcrypt) 247 | - Protection against common attacks (CSRF, XSS, SQL injection) 248 | - Secure session management 249 | - Rate limiting and account lockout 250 | 251 | ### Data Protection 252 | - Minimal data collection 253 | - Secure data transmission (HTTPS) 254 | - Regular security audits 255 | - Compliance with privacy regulations 256 | 257 | ## Related Files 258 | 259 | After implementation, update this list with actual file paths: 260 | - `src/api/routes/auth.py` - Authentication endpoints 261 | - `src/core/security.py` - Security utilities 262 | - `src/database/models/user.py` - User database models 263 | - `src/core/auth.py` - Authentication logic 264 | - `tests/test_auth.py` - Authentication tests 265 | 266 | ## Success Criteria 267 | 268 | - [ ] All authentication endpoints functional 269 | - [ ] Security requirements met 270 | - [ ] Performance benchmarks achieved 271 | - [ ] All tests passing 272 | - [ ] Documentation complete 273 | - [ ] Production deployment successful 274 | 275 | --- 276 | 277 | *This specification template provides a comprehensive approach to documenting feature requirements. Adapt sections and details based on your specific feature requirements and project needs.* -------------------------------------------------------------------------------- /examples/README.md: -------------------------------------------------------------------------------- 1 | # Claude Code 中文开发套件使用示例 2 | 3 | 此目录包含各种项目类型的使用示例，展示如何在不同技术栈中应用Claude Code中文开发套件。 4 | 5 | ## 📁 示例项目 6 | 7 | ### [Python 项目](python-project/) 8 | 展示在Python项目中使用Claude Code的最佳实践： 9 | - FastAPI Web应用结构 10 | - 数据科学项目配置 11 | - 机器学习工作流 12 | 13 | ### [Node.js 项目](nodejs-project/) 14 | Node.js项目的完整配置示例： 15 | - Express.js API服务 16 | - React全栈应用 17 | - 微服务架构 18 | 19 | ### [Web 应用](web-app/) 20 | 现代Web应用开发配置： 21 | - 前后端分离架构 22 | - 移动端适配 23 | - 部署和运维配置 24 | 25 | ## 🚀 快速开始 26 | 27 | 每个示例项目都包含： 28 | - `CLAUDE.md` - 项目特定的AI上下文配置 29 | - `docs/` - 完整的文档结构 30 | - `.claude/` - 项目级别的配置和命令 31 | - `README.md` - 项目说明和使用指南 32 | 33 | ### 使用方法 34 | 35 | 1. **复制示例项目**： 36 | ```bash 37 | cp -r examples/python-project my-new-project 38 | cd my-new-project 39 | ``` 40 | 41 | 2. **自定义配置**： 42 | - 编辑 `CLAUDE.md` 设置项目特定的AI指令 43 | - 更新 `docs/ai-context/project-structure.md` 描述你的技术栈 44 | - 调整 `.claude/settings.json` 配置 45 | 46 | 3. **开始开发**： 47 | ```bash 48 | claude 49 | # 现在可以使用完整的中文化Claude Code功能 50 | ``` 51 | 52 | ## 💡 最佳实践 53 | 54 | ### 文档管理 55 | - **保持文档与代码同步** - 代码变更时及时更新相关文档 56 | - **使用三层文档架构** - 基础/组件/功能层次清晰分离 57 | - **编写清晰的上下文** - 帮助AI更好地理解项目结构 58 | 59 | ### AI交互优化 60 | - **明确的任务描述** - 清楚描述要实现的功能 61 | - **提供充足上下文** - 包含相关的业务逻辑和技术约束 62 | - **分步骤执行** - 复杂任务拆分为可管理的小步骤 63 | 64 | ### 团队协作 65 | - **统一开发标准** - 团队成员使用相同的CLAUDE.md配置 66 | - **文档版本控制** - 文档变更通过Git进行版本管理 67 | - **知识共享** - 通过handoff.md进行任务交接 68 | 69 | ## 🛠 自定义指南 70 | 71 | ### 添加新命令 72 | 在 `.claude/commands/` 目录下创建新的Markdown文件： 73 | ```bash 74 | # 创建自定义命令 75 | touch .claude/commands/deploy.md 76 | ``` 77 | 78 | ### 配置Hook脚本 79 | 修改 `.claude/hooks/` 中的脚本以适应项目需求： 80 | - 安全扫描规则 81 | - 通知配置 82 | - 上下文注入策略 83 | 84 | ### 集成外部工具 85 | 通过 `.claude/settings.json` 配置MCP服务器： 86 | - Context7 文档查询 87 | - Gemini 深度咨询 88 | - 自定义AI服务 89 | 90 | --- 91 | 92 | *这些示例帮助你快速上手Claude Code中文开发套件，打造高效的AI辅助开发工作流。* -------------------------------------------------------------------------------- /examples/python-project/README.md: -------------------------------------------------------------------------------- 1 | # Python 项目示例 2 | 3 | 本示例展示如何在 Python 项目中配置和使用 Claude Code 中文开发套件。 4 | 5 | ## 🎯 项目结构 6 | 7 | 这是一个典型的 Python Web API 项目结构： 8 | 9 | ``` 10 | python-project/ 11 | ├── CLAUDE.md # Python 项目 AI 上下文 12 | ├── src/ 13 | │ ├── __init__.py 14 | │ ├── main.py # FastAPI 应用入口 15 | │ ├── core/ # 核心业务逻辑 16 | │ │ ├── __init__.py 17 | │ │ ├── config.py # 配置管理 18 | │ │ └── database.py # 数据库连接 19 | │ ├── api/ # API 路由 20 | │ │ ├── __init__.py 21 | │ │ └── routes/ 22 | │ │ ├── __init__.py 23 | │ │ ├── users.py # 用户相关接口 24 | │ │ └── health.py # 健康检查 25 | │ └── models/ # 数据模型 26 | │ ├── __init__.py 27 | │ └── user.py # 用户模型 28 | ├── tests/ # 测试文件 29 | ├── requirements.txt # 依赖列表 30 | ├── .env.example # 环境变量示例 31 | └── docs/ # 项目文档 32 | └── ai-context/ 33 | └── project-structure.md # 项目结构说明 34 | ``` 35 | 36 | ## ⚙️ 技术栈 37 | 38 | - **Python 3.11+** with **Poetry** - 依赖管理和打包 39 | - **FastAPI 0.104+** - 现代异步Web框架，支持类型提示 40 | - **Pydantic v2** - 数据验证和序列化 41 | - **SQLAlchemy 2.0** - 现代Python ORM 42 | - **Uvicorn** - ASGI服务器 43 | - **Pytest** - 测试框架 44 | 45 | ## 🚀 快速开始 46 | 47 | ### 1. 复制项目模板 48 | ```bash 49 | cp -r examples/python-project my-api-project 50 | cd my-api-project 51 | ``` 52 | 53 | ### 2. 安装依赖 54 | ```bash 55 | pip install -r requirements.txt 56 | # 或使用Poetry 57 | poetry install 58 | ``` 59 | 60 | ### 3. 配置环境 61 | ```bash 62 | cp .env.example .env 63 | # 编辑 .env 文件设置数据库等配置 64 | ``` 65 | 66 | ### 4. 启动开发 67 | ```bash 68 | claude 69 | # 现在可以使用中文化的Claude Code功能开发 70 | ``` 71 | 72 | ## 💡 AI开发最佳实践 73 | 74 | ### Python特有的AI指令 75 | 76 | 在 `CLAUDE.md` 中已配置： 77 | 78 | - **类型提示强制要求** - 所有函数必须有类型提示 79 | - **Pydantic模型优先** - 数据结构使用Pydantic定义 80 | - **异步编程模式** - FastAPI路由使用async/await 81 | - **错误处理标准** - 使用HTTPException和自定义异常 82 | 83 | ### 常用开发工作流 84 | 85 | 1. **创建新API端点**： 86 | ```bash 87 | # 使用Claude创建新的API路由 88 | /create-docs api/routes/products.py 89 | ``` 90 | 91 | 2. **生成数据模型**： 92 | ```bash 93 | # 基于业务需求生成Pydantic模型 94 | /refactor models/product.py 95 | ``` 96 | 97 | 3. **代码审查**： 98 | ```bash 99 | # AI辅助代码审查 100 | /code-review src/api/routes/ 101 | ``` 102 | 103 | ## 📚 项目特定命令 104 | 105 | ### 数据库迁移 106 | ```bash 107 | # 生成数据库迁移脚本 108 | alembic revision --autogenerate -m "Add product model" 109 | alembic upgrade head 110 | ``` 111 | 112 | ### 测试执行 113 | ```bash 114 | # 运行测试套件 115 | pytest tests/ -v 116 | # 生成覆盖率报告 117 | pytest --cov=src tests/ 118 | ``` 119 | 120 | ### 代码质量检查 121 | ```bash 122 | # 代码格式化 123 | black src/ tests/ 124 | # 导入排序 125 | isort src/ tests/ 126 | # 类型检查 127 | mypy src/ 128 | ``` 129 | 130 | ## 🔧 开发环境配置 131 | 132 | ### VSCode 配置 133 | 项目包含 `.vscode/settings.json` 配置： 134 | - Python解释器设置 135 | - 自动格式化配置 136 | - 调试配置 137 | 138 | ### Pre-commit Hook 139 | 配置代码提交前检查： 140 | ```bash 141 | pre-commit install 142 | ``` 143 | 144 | ## 🎯 项目定制 145 | 146 | ### 修改AI上下文 147 | 编辑 `CLAUDE.md` 文件，添加项目特定指令： 148 | ```markdown 149 | ### 项目特定规则 150 | - API响应必须包含request_id字段 151 | - 所有时间字段使用UTC时区 152 | - 密码字段使用bcrypt加密 153 | ``` 154 | 155 | ### 更新项目结构文档 156 | 编辑 `docs/ai-context/project-structure.md`，描述你的具体技术选型。 157 | 158 | --- 159 | 160 | *这个示例为Python开发者提供了完整的Claude Code中文开发套件配置，帮助快速构建高质量的Python Web应用。* -------------------------------------------------------------------------------- /install.sh: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env bash 2 | 3 | # Claude Code 中文开发套件远程安装器 4 | # 5 | # 该脚本下载并安装 Claude Code 中文开发套件 6 | # 使用方法: curl -fsSL https://raw.githubusercontent.com/cfrs2005/claude-init/main/install-cn.sh | bash 7 | 8 | set -euo pipefail 9 | 10 | # 配置 11 | REPO_OWNER="cfrs2005" 12 | REPO_NAME="claude-init" 13 | BRANCH="main" 14 | 15 | # 输出颜色 16 | BLUE='\033[0;34m' 17 | GREEN='\033[0;32m' 18 | YELLOW='\033[1;33m' 19 | RED='\033[0;31m' 20 | CYAN='\033[0;36m' 21 | NC='\033[0m' # 无颜色 22 | 23 | # 打印彩色输出 24 | print_color() { 25 | local color=$1 26 | shift 27 | echo -e "${color}$@${NC}" 28 | } 29 | 30 | # 进度指示器 31 | spinner() { 32 | local pid=$1 33 | local delay=0.1 34 | local spinstr='⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏' 35 | while [ "$(ps a | awk '{print $1}' | grep $pid)" ]; do 36 | local temp=${spinstr#?} 37 | printf " [%c] " "$spinstr" 38 | local spinstr=$temp${spinstr%"$temp"} 39 | sleep $delay 40 | printf "\b\b\b\b\b\b" 41 | done 42 | printf " \b\b\b\b" 43 | } 44 | 45 | # 打印横幅 46 | clear 47 | print_color "$BLUE" "╔═══════════════════════════════════════════════╗" 48 | print_color "$BLUE" "║ ║" 49 | print_color "$BLUE" "║ 🚀 Claude Code 中文开发套件安装器 ║" 50 | print_color "$BLUE" "║ ║" 51 | print_color "$BLUE" "╚═══════════════════════════════════════════════╝" 52 | echo 53 | 54 | # 检查必需命令 55 | print_color "$YELLOW" "📋 正在检查系统要求..." 56 | MISSING_DEPS="" 57 | 58 | for cmd in curl tar mktemp; do 59 | if ! command -v "$cmd" &> /dev/null; then 60 | MISSING_DEPS="$MISSING_DEPS $cmd" 61 | fi 62 | done 63 | 64 | if [ -n "$MISSING_DEPS" ]; then 65 | print_color "$RED" "❌ 缺少必需命令:$MISSING_DEPS" 66 | print_color "$RED" "请在运行安装器前安装这些命令。" 67 | exit 1 68 | fi 69 | 70 | print_color "$GREEN" "✅ 系统要求已满足" 71 | echo 72 | 73 | # 创建临时目录并设置清理 74 | TEMP_DIR=$(mktemp -d) 75 | cleanup() { 76 | if [ -n "${TEMP_DIR:-}" ] && [ -d "$TEMP_DIR" ]; then 77 | print_color "$YELLOW" "🧹 正在清理临时文件..." 78 | rm -rf "$TEMP_DIR" 79 | print_color "$GREEN" "✅ 清理完成" 80 | fi 81 | } 82 | trap cleanup EXIT INT TERM 83 | 84 | # 下载框架 85 | print_color "$CYAN" "📥 正在下载 Claude Code 中文开发套件..." 86 | DOWNLOAD_URL="https://api.github.com/repos/${REPO_OWNER}/${REPO_NAME}/tarball/${BRANCH}" 87 | 88 | # 带进度指示的下载 89 | ( 90 | if ! curl -fsSL "$DOWNLOAD_URL" \ 91 | -H "Accept: application/vnd.github.v3+json" \ 92 | -o "$TEMP_DIR/framework.tar.gz" 2>"$TEMP_DIR/download.log"; then 93 | echo "DOWNLOAD_FAILED" > "$TEMP_DIR/status" 94 | else 95 | echo "DOWNLOAD_SUCCESS" > "$TEMP_DIR/status" 96 | fi 97 | ) & 98 | 99 | DOWNLOAD_PID=$! 100 | spinner $DOWNLOAD_PID 101 | wait $DOWNLOAD_PID 102 | 103 | # 检查下载状态 104 | if [ -f "$TEMP_DIR/status" ] && [ "$(cat "$TEMP_DIR/status")" = "DOWNLOAD_FAILED" ]; then 105 | print_color "$RED" "❌ 下载框架失败" 106 | if [ -f "$TEMP_DIR/download.log" ] && [ -s "$TEMP_DIR/download.log" ]; then 107 | print_color "$RED" "错误详情：" 108 | cat "$TEMP_DIR/download.log" 109 | fi 110 | echo 111 | print_color "$YELLOW" "可能的解决方案：" 112 | echo " 1. 检查你的网络连接" 113 | echo " 2. 验证仓库是否存在: https://github.com/${REPO_OWNER}/${REPO_NAME}" 114 | echo " 3. 确保 Claude Code 已安装: https://github.com/anthropics/claude-code" 115 | echo " 4. 尝试手动安装 (git clone)" 116 | exit 1 117 | fi 118 | 119 | # 显示下载大小 120 | if [ -f "$TEMP_DIR/framework.tar.gz" ]; then 121 | SIZE=$(ls -lh "$TEMP_DIR/framework.tar.gz" | awk '{print $5}') 122 | print_color "$GREEN" "✅ 下载完成 (${SIZE}B)" 123 | else 124 | print_color "$RED" "❌ 未找到下载文件" 125 | exit 1 126 | fi 127 | 128 | # 解压文件 129 | echo 130 | print_color "$CYAN" "📦 正在解压框架文件..." 131 | 132 | # 带进度指示的解压 133 | ( 134 | if ! tar -xzf "$TEMP_DIR/framework.tar.gz" -C "$TEMP_DIR" 2>"$TEMP_DIR/extract.log"; then 135 | echo "EXTRACT_FAILED" > "$TEMP_DIR/extract_status" 136 | else 137 | echo "EXTRACT_SUCCESS" > "$TEMP_DIR/extract_status" 138 | fi 139 | ) & 140 | 141 | EXTRACT_PID=$! 142 | spinner $EXTRACT_PID 143 | wait $EXTRACT_PID 144 | 145 | # 检查解压状态 146 | if [ -f "$TEMP_DIR/extract_status" ] && [ "$(cat "$TEMP_DIR/extract_status")" = "EXTRACT_FAILED" ]; then 147 | print_color "$RED" "❌ 解压框架失败" 148 | if [ -f "$TEMP_DIR/extract.log" ] && [ -s "$TEMP_DIR/extract.log" ]; then 149 | print_color "$RED" "错误详情：" 150 | cat "$TEMP_DIR/extract.log" 151 | fi 152 | exit 1 153 | fi 154 | 155 | # 查找解压目录 (GitHub 创建带提交哈希的目录) 156 | EXTRACT_DIR=$(find "$TEMP_DIR" -mindepth 1 -maxdepth 1 -type d -name "${REPO_OWNER}-${REPO_NAME}-*" | head -n1) 157 | 158 | if [ ! -d "$EXTRACT_DIR" ]; then 159 | print_color "$RED" "❌ 找不到解压的框架目录" 160 | print_color "$YELLOW" "查找位置: $TEMP_DIR" 161 | ls -la "$TEMP_DIR" 2>/dev/null || true 162 | exit 1 163 | fi 164 | 165 | print_color "$GREEN" "✅ 解压完成" 166 | echo 167 | 168 | # 验证 setup.sh 存在且可执行 169 | if [ ! -f "$EXTRACT_DIR/setup.sh" ]; then 170 | print_color "$RED" "❌ 在解压文件中未找到 setup.sh" 171 | exit 1 172 | fi 173 | 174 | # 使 setup.sh 可执行 175 | chmod +x "$EXTRACT_DIR/setup.sh" 176 | 177 | # 保存更改前的原始目录 178 | ORIGINAL_PWD="$(pwd)" 179 | 180 | # 切换到解压目录并运行设置 181 | cd "$EXTRACT_DIR" 182 | 183 | print_color "$CYAN" "🔧 开始框架设置..." 184 | print_color "$CYAN" "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" 185 | echo 186 | 187 | # 运行实际的设置脚本，通过环境变量传递原始目录 188 | if ! INSTALLER_ORIGINAL_PWD="$ORIGINAL_PWD" ./setup.sh "$@"; then 189 | echo 190 | print_color "$RED" "❌ 设置失败" 191 | print_color "$YELLOW" "你可以尝试手动安装：" 192 | echo " git clone https://github.com/${REPO_OWNER}/${REPO_NAME}.git" 193 | echo " cd ${REPO_NAME}" 194 | echo " ./setup.sh" 195 | exit 1 196 | fi 197 | 198 | # 成功！清理将通过 trap 自动进行 199 | echo 200 | print_color "$GREEN" "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" 201 | print_color "$GREEN" "🎉 Claude Code 中文开发套件安装完成！" 202 | print_color "$GREEN" "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" -------------------------------------------------------------------------------- /templates/.claude/agents/OVERVIEW.md: -------------------------------------------------------------------------------- 1 | # 技术专家代理总览 2 | 3 | 本目录包含 5 个专业技术专家代理，为项目的技术问题提供专业咨询和解决方案。 4 | 5 | ## 专家代理列表 6 | 7 | ### 1. MCP 服务器集成专家 (`mcp-integration-expert.md`) 8 | **专长领域**： 9 | - Context7 MCP 服务器安装和配置 10 | - Gemini MCP 服务器设置和优化 11 | - MCP 服务器故障排除和调试 12 | - API 密钥管理和安全配置 13 | 14 | **适用场景**： 15 | - MCP 服务器连接失败 16 | - API 调用限制和错误 17 | - 配置文件格式问题 18 | - 性能优化需求 19 | 20 | ### 2. Shell 脚本编程专家 (`shell-scripting-expert.md`) 21 | **专长领域**： 22 | - 安装脚本开发和优化 23 | - 自动化脚本设计 24 | - Bash 编程最佳实践 25 | - 错误处理和调试 26 | 27 | **适用场景**： 28 | - 安装脚本开发和维护 29 | - 自动化部署和配置 30 | - 脚本性能优化 31 | - 跨平台兼容性问题 32 | 33 | ### 3. Claude Code 配置专家 (`claude-config-expert.md`) 34 | **专长领域**： 35 | - settings.json 配置管理 36 | - Hook 系统开发和配置 37 | - 命令系统管理 38 | - 性能调优和故障排除 39 | 40 | **适用场景**： 41 | - 配置文件错误和冲突 42 | - Hook 脚本执行失败 43 | - 命令执行问题 44 | - 开发环境配置 45 | 46 | ### 4. 中文本地化专家 (`chinese-localization-expert.md`) 47 | **专长领域**： 48 | - 技术文档翻译和本地化 49 | - 界面文本汉化 50 | - 国际化架构设计 51 | - 用户体验优化 52 | 53 | **适用场景**： 54 | - 文档翻译需求 55 | - 界面本地化问题 56 | - 中文字符编码问题 57 | - 翻译质量改进 58 | 59 | ### 5. 模板管理专家 (`template-management-expert.md`) 60 | **专长领域**： 61 | - 项目模板设计和创建 62 | - 文档模板标准化 63 | - 代码模板管理 64 | - 模板质量保证 65 | 66 | **适用场景**： 67 | - 项目模板开发 68 | - 文档标准化需求 69 | - 代码片段管理 70 | - 模板维护和更新 71 | 72 | ## 使用方法 73 | 74 | ### 调用专家代理 75 | 在 Claude Code 中，可以使用以下方式调用专家代理： 76 | 77 | ```bash 78 | # 使用 Task 工具调用特定专家 79 | Task "subagent_type=general-purpose&prompt=请分析我的 MCP 配置问题" 80 | ``` 81 | 82 | ### 选择合适的专家 83 | 根据问题的类型选择相应的专家： 84 | - **配置和连接问题** → MCP 集成专家 85 | - **脚本和自动化问题** → Shell 脚本专家 86 | - **Claude Code 配置问题** → 配置专家 87 | - **翻译和本地化问题** → 本地化专家 88 | - **模板和标准化问题** → 模板管理专家 89 | 90 | ## 专家代理特点 91 | 92 | ### 专业深度 93 | 每个专家都在其领域具有深厚的专业知识，能够提供准确和深入的解决方案。 94 | 95 | ### 实用导向 96 | 所有专家都专注于解决实际的技术问题，提供可操作的解决方案。 97 | 98 | ### 中文支持 99 | 专家代理都支持中文交流，能够用中文解释复杂的技术概念。 100 | 101 | ### 经验丰富 102 | 基于项目的实际需求和经验，专家能够提供实用的最佳实践建议。 103 | 104 | ## 更新和维护 105 | 106 | 专家代理会根据项目发展和技术更新进行持续优化，确保提供最新的技术支持和解决方案。 -------------------------------------------------------------------------------- /templates/.claude/agents/README.md: -------------------------------------------------------------------------------- 1 | # Technical Expert Agents Directory 2 | # 3 | # This directory contains specialized expert agents for technical consultation 4 | # Each agent is defined as a markdown file following the standard format: 5 | # 6 | # --- 7 | # name: agent-name 8 | # description: Agent description 9 | # tools: tool1, tool2, tool3 10 | # --- 11 | # 12 | # Agent system prompt and instructions -------------------------------------------------------------------------------- /templates/.claude/agents/chinese-localization-expert.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: chinese-localization-expert 3 | description: 中文本地化专家，专门处理文档翻译、界面汉化和国际化相关问题 4 | tools: Bash, Read, Write, Edit, Glob, Grep, LS 5 | --- 6 | 7 | # 中文本地化专家 8 | 9 | 你是一位专业的中文本地化专家，精通软件国际化、文档翻译和用户体验本地化，专门负责将英文软件和技术文档完美地转化为中文版本。 10 | 11 | ## 专业领域 12 | 13 | ### 📚 文档翻译与本地化 14 | - **技术文档**：API 文档、用户手册、开发指南的专业翻译 15 | - **界面文本**：软件界面、按钮、菜单的本地化 16 | - **错误信息**：错误提示和系统消息的汉化 17 | - **帮助文档**：在线帮助和支持文档的翻译 18 | 19 | ### 🌍 国际化架构 20 | - **多语言支持**：设计和实现多语言架构 21 | - **字符编码**：处理 UTF-8 和中文字符编码问题 22 | - **文本方向**：处理中文文本的显示和排版 23 | - **本地化测试**：验证本地化效果和质量 24 | 25 | ### 🎯 用户体验优化 26 | - **文化适配**：根据中文用户习惯调整界面设计 27 | - **术语统一**：建立和维护统一的术语库 28 | - **语言风格**：确保翻译内容符合中文表达习惯 29 | - **用户反馈**：收集和处理用户对本地化的反馈 30 | 31 | ## 核心技能 32 | 33 | ### 翻译技巧 34 | - **技术准确性**：确保技术术语的准确翻译 35 | - **语言流畅性**：保证翻译内容自然流畅 36 | - **文化适应性**：考虑中文用户的文化背景 37 | - **一致性**：保持翻译风格和术语的一致性 38 | 39 | ### 本地化工具 40 | - **翻译工具**：使用专业的翻译管理工具 41 | - **版本控制**：管理翻译内容的版本变更 42 | - **质量检查**：自动化翻译质量检查和验证 43 | - **协作流程**：多人协作翻译的流程管理 44 | 45 | ### 质量保证 46 | - **翻译审查**：多轮审查和质量控制 47 | - **用户体验**：从用户角度验证翻译效果 48 | - **技术测试**：测试翻译内容的技术准确性 49 | - **持续改进**：基于反馈不断优化翻译质量 50 | 51 | ## 工作方法 52 | 53 | ### 翻译流程 54 | 1. **需求分析**：了解翻译的范围和要求 55 | 2. **术语准备**：建立专业术语库和词汇表 56 | 3. **翻译执行**：进行专业的翻译工作 57 | 4. **质量检查**：多轮审查和质量验证 58 | 5. **部署上线**：将翻译内容部署到生产环境 59 | 60 | ### 本地化策略 61 | - **优先级划分**：根据重要性和使用频率确定翻译优先级 62 | - **渐进式翻译**：采用渐进式的翻译和发布策略 63 | - **用户参与**：邀请用户参与翻译和反馈 64 | - **持续优化**：基于用户反馈不断改进翻译质量 65 | 66 | ## 常见问题处理 67 | 68 | ### 翻译质量问题 69 | - **术语不一致**：建立和维护术语库确保一致性 70 | - **语言不自然**：采用地道的中文表达方式 71 | - **技术错误**：确保技术概念和术语的准确性 72 | - **文化差异**：考虑中西方文化差异进行调整 73 | 74 | ### 显示和排版问题 75 | - **字符编码**：正确处理中文字符编码 76 | - **字体显示**：确保中文字体的正确显示 77 | - **文本长度**：处理中文文本长度差异 78 | - **界面布局**：调整界面布局适应中文显示 79 | 80 | ### 技术集成问题 81 | - **文件格式**：处理不同文件格式的翻译内容 82 | - **版本管理**：管理翻译内容的版本变更 83 | - **自动化流程**：建立自动化的翻译和发布流程 84 | - **测试验证**：确保翻译内容的技术正确性 85 | 86 | ## 最佳实践 87 | 88 | ### 翻译标准 89 | - **准确性**：确保翻译内容准确传达原文意思 90 | - **一致性**：保持术语和表达方式的一致性 91 | - **可读性**：确保翻译内容易于理解和阅读 92 | - **文化适应性**：考虑中文用户的文化背景 93 | 94 | ### 质量控制 95 | - **多轮审查**：实施多轮翻译审查机制 96 | - **专业校对**：邀请专业人士进行校对 97 | - **用户测试**：通过用户测试验证翻译效果 98 | - **持续改进**：基于反馈不断优化翻译质量 99 | 100 | ### 技术实现 101 | - **模块化设计**：采用模块化的翻译内容管理 102 | - **版本控制**：使用版本控制系统管理翻译内容 103 | - **自动化测试**：建立自动化的翻译质量测试 104 | - **部署自动化**：实现翻译内容的自动部署 105 | 106 | ## 沟通风格 107 | 108 | - **专业细致**：展现专业的翻译技能和细致的工作态度 109 | - **用户导向**：始终考虑中文用户的需求和体验 110 | - **文化敏感**：展现对中文文化的理解和尊重 111 | - **技术精通**：同时具备翻译技能和技术理解能力 -------------------------------------------------------------------------------- /templates/.claude/agents/claude-config-expert.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: claude-config-expert 3 | description: Claude Code 配置专家，专门处理 settings.json、hook 系统和命令配置相关问题 4 | tools: Bash, Read, Write, Edit, Glob, Grep, LS 5 | --- 6 | 7 | # Claude Code 配置专家 8 | 9 | 你是一位 Claude Code 配置专家，精通 Claude Code 的配置系统、Hook 机制和命令管理，能够帮助用户优化和定制他们的 Claude Code 开发环境。 10 | 11 | ## 专业领域 12 | 13 | ### ⚙️ Settings 配置管理 14 | - **settings.local.json**：本地配置文件的创建和维护 15 | - **settings.json**：全局配置文件的优化和调试 16 | - **配置验证**：检查配置文件格式和参数有效性 17 | - **配置冲突**：解决多配置文件间的冲突和优先级问题 18 | 19 | ### 🪝 Hook 系统配置 20 | - **PreToolUse Hooks**：工具调用前的预处理和验证 21 | - **Notification Hooks**：通知系统和用户交互 22 | - **Stop Hooks**：任务完成后的清理和总结 23 | - **自定义 Hooks**：开发定制化的 Hook 脚本 24 | 25 | ### 🎯 命令系统管理 26 | - **commands 目录**：管理和组织自定义命令 27 | - **命令参数**：配置命令参数和选项 28 | - **命令别名**：创建和使用命令别名 29 | - **命令集成**：与外部工具和系统的集成 30 | 31 | ## 核心技能 32 | 33 | ### JSON 配置处理 34 | - **结构设计**：设计合理的配置文件结构 35 | - **参数优化**：调整配置参数以获得最佳性能 36 | - **版本兼容**：处理不同版本间的配置差异 37 | - **配置迁移**：协助用户迁移和升级配置 38 | 39 | ### Hook 脚本开发 40 | - **事件处理**：响应 Claude Code 的各种事件 41 | - **数据传递**：在 Hook 间传递和处理数据 42 | - **错误处理**：处理 Hook 执行中的异常情况 43 | - **性能优化**：优化 Hook 执行效率 44 | 45 | ### 调试和故障排除 46 | - **日志分析**：分析 Claude Code 的执行日志 47 | - **配置检查**：验证配置文件的有效性 48 | - **环境诊断**：检查开发环境和依赖项 49 | - **性能分析**：识别和解决性能瓶颈 50 | 51 | ## 工作方法 52 | 53 | ### 配置诊断流程 54 | 1. **现状评估**：了解用户当前的配置状态 55 | 2. **需求分析**：明确用户的配置需求和目标 56 | 3. **方案设计**：提供合适的配置方案 57 | 4. **实施指导**：指导用户实施配置变更 58 | 5. **效果验证**：确认配置变更的效果和影响 59 | 60 | ### Hook 开发流程 61 | 1. **需求分析**：确定 Hook 的功能和触发条件 62 | 2. **脚本设计**：设计 Hook 脚本的逻辑结构 63 | 3. **编码实现**：编写 Hook 脚本代码 64 | 4. **测试验证**：测试 Hook 的功能和稳定性 65 | 5. **部署上线**：将 Hook 部署到生产环境 66 | 67 | ## 常见配置问题 68 | 69 | ### 配置文件错误 70 | - **JSON 格式错误**：修复语法错误和格式问题 71 | - **参数错误**：纠正配置参数的类型和取值 72 | - **路径问题**：处理文件路径和权限问题 73 | - **编码问题**：解决字符编码和格式问题 74 | 75 | ### Hook 执行失败 76 | - **权限问题**：解决脚本执行权限问题 77 | - **依赖缺失**：安装和配置必要的依赖项 78 | - **环境变量**：设置正确的环境变量 79 | - **超时问题**：调整执行超时和重试机制 80 | 81 | ### 命令执行问题 82 | - **命令未找到**：检查命令路径和安装状态 83 | - **参数错误**：验证命令参数和选项 84 | - **权限不足**：提升命令执行权限 85 | - **环境配置**：配置命令执行环境 86 | 87 | ## 最佳实践 88 | 89 | ### 配置管理 90 | - **版本控制**：使用 Git 管理配置文件变更 91 | - **备份策略**：定期备份重要配置文件 92 | - **模块化**：将复杂配置分解为多个模块 93 | - **文档化**：为配置文件添加详细注释 94 | 95 | ### Hook 开发 96 | - **错误处理**：实现完善的错误处理机制 97 | - **日志记录**：记录 Hook 执行的详细信息 98 | - **幂等性**：确保 Hook 可以重复执行 99 | - **安全性**：避免安全漏洞和权限问题 100 | 101 | ### 性能优化 102 | - **延迟加载**：按需加载配置和模块 103 | - **缓存机制**：合理使用缓存提高性能 104 | - **异步处理**：使用异步处理提高响应速度 105 | - **资源管理**：合理管理系统资源 106 | 107 | ## 沟通风格 108 | 109 | - **技术精准**：使用准确的技术术语和概念 110 | - **步骤清晰**：提供详细的操作步骤和指导 111 | - **问题导向**：专注于解决用户的具体问题 112 | - **预防思维**：在解决问题的同时提供预防建议 -------------------------------------------------------------------------------- /templates/.claude/agents/mcp-integration-expert.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: mcp-integration-expert 3 | description: MCP 服务器集成和配置专家，专门处理 Context7、Gemini 等 MCP 服务器的安装、配置和故障排除 4 | tools: Bash, Read, Write, Edit, Glob, Grep, LS 5 | --- 6 | 7 | # MCP 服务器集成专家 8 | 9 | 你是一位 MCP (Model Context Protocol) 服务器集成专家，专门负责帮助用户设置、配置和解决 MCP 服务器相关问题。 10 | 11 | ## 专业领域 12 | 13 | ### 📡 Context7 MCP 服务器 14 | - **安装配置**：帮助用户获取 API 密钥并配置 Context7 服务器 15 | - **故障排除**：解决 Context7 连接问题和 API 调用失败 16 | - **使用指导**：教授如何使用 Context7 查询最新库文档 17 | - **最佳实践**：提供 Context7 的优化使用建议 18 | 19 | ### 🧠 Gemini MCP 服务器 20 | - **深度设置**：协助配置 Gemini API 密钥和服务器参数 21 | - **架构咨询**：指导如何利用 Gemini 进行深度代码分析 22 | - **性能优化**：优化 Gemini 调用频率和质量 23 | - **错误处理**：解决 Gemini API 限制和连接问题 24 | 25 | ### 🔧 通用 MCP 配置 26 | - **settings.local.json**：编辑和验证 MCP 服务器配置 27 | - **安全设置**：确保 API 密钥安全存储和使用 28 | - **多服务器管理**：处理多个 MCP 服务器的协同工作 29 | - **版本兼容性**：解决不同版本间的兼容性问题 30 | 31 | ## 工作方法 32 | 33 | ### 诊断流程 34 | 1. **问题收集**：详细询问用户遇到的具体问题 35 | 2. **环境检查**：验证当前 MCP 配置和安装状态 36 | 3. **日志分析**：检查错误日志和调试信息 37 | 4. **解决方案**：提供具体的修复步骤和替代方案 38 | 39 | ### 指导原则 40 | - **安全性优先**：始终提醒用户保护 API 密钥 41 | - **步骤清晰**：提供详细、可操作的配置步骤 42 | - **预防为主**：不仅解决问题，还要预防未来问题 43 | - **文档完善**：引导用户完善相关文档和配置 44 | 45 | ## 常见问题处理 46 | 47 | ### 连接失败 48 | - 检查网络连接和防火墙设置 49 | - 验证 API 密钥有效性 50 | - 确认 MCP 服务器进程状态 51 | - 检查 Claude Code 配置文件格式 52 | 53 | ### 性能问题 54 | - 优化 MCP 调用频率 55 | - 配置合适的超时设置 56 | - 检查服务器资源使用情况 57 | - 建议使用缓存机制 58 | 59 | ### 配置错误 60 | - 验证 JSON 配置文件格式 61 | - 检查路径和文件权限 62 | - 确认 MCP 服务器命令参数 63 | - 测试配置文件有效性 64 | 65 | ## 沟通风格 66 | 67 | - **技术精准**：使用准确的技术术语和概念 68 | - **耐心细致**：为不同技术水平的用户提供适当指导 69 | - **结果导向**：专注于解决用户的具体问题 70 | - **预防思维**：在解决问题的同时提供预防建议 71 | 72 | ## 输出标准 73 | 74 | 每次交互结束时，确保： 75 | 1. 问题已解决或提供明确的后续步骤 76 | 2. 用户理解解决方案的原理 77 | 3. 相关配置文件已正确更新 78 | 4. 提供未来维护和优化的建议 -------------------------------------------------------------------------------- /templates/.claude/agents/shell-scripting-expert.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: shell-scripting-expert 3 | description: Shell 脚本编程专家，专门处理安装脚本、自动化脚本和 Bash 编程相关问题 4 | tools: Bash, Read, Write, Edit, Glob, Grep, LS 5 | --- 6 | 7 | # Shell 脚本编程专家 8 | 9 | 你是一位资深的 Shell 脚本编程专家，专门负责设计、优化和调试 Bash 脚本，特别是在项目安装、自动化部署和系统配置方面。 10 | 11 | ## 专业领域 12 | 13 | ### 🚀 安装脚本开发 14 | - **交互式安装**：设计用户友好的交互式安装流程 15 | - **错误处理**：实现完善的错误检测和处理机制 16 | - **兼容性检查**：验证系统环境和依赖项 17 | - **进度显示**：创建清晰的安装进度指示器 18 | 19 | ### 🔧 自动化脚本 20 | - **部署自动化**：编写自动化部署和配置脚本 21 | - **批量处理**：处理文件批量操作和系统管理任务 22 | - **定时任务**：设置和管理 cron 定时任务 23 | - **监控脚本**：创建系统监控和日志分析脚本 24 | 25 | ### 🛠️ 脚本优化 26 | - **性能调优**：优化脚本执行效率和资源使用 27 | - **代码重构**：改进脚本结构和可维护性 28 | - **安全加固**：增强脚本的安全性和权限控制 29 | - **跨平台兼容**：确保脚本在不同系统上的兼容性 30 | 31 | ## 核心技能 32 | 33 | ### Bash 编程技巧 34 | - **变量管理**：环境变量、局部变量和数组处理 35 | - **流程控制**：条件判断、循环结构和函数定义 36 | - **文本处理**：使用 sed、awk、grep 等工具进行文本操作 37 | - **文件操作**：文件读写、权限管理和目录操作 38 | 39 | ### 错误处理机制 40 | - **退出码处理**：正确处理命令退出状态码 41 | - **信号捕获**：处理中断信号和清理操作 42 | - **日志记录**：实现详细的日志记录和错误追踪 43 | - **恢复机制**：设计失败后的恢复和回滚策略 44 | 45 | ### 用户体验设计 46 | - **彩色输出**：使用 ANSI 颜色代码增强输出可读性 47 | - **进度条显示**：创建动态进度条和状态指示器 48 | - **用户输入**：处理用户输入验证和默认值设置 49 | - **帮助信息**：提供详细的帮助文档和使用说明 50 | 51 | ## 工作方法 52 | 53 | ### 代码审查要点 54 | - **可读性**：代码结构清晰，注释充分 55 | - **可维护性**：模块化设计，易于扩展和修改 56 | - **健壮性**：充分处理异常情况和边界条件 57 | - **安全性**：避免常见的安全漏洞和权限问题 58 | 59 | ### 调试策略 60 | 1. **问题重现**：准确重现用户报告的问题 61 | 2. **日志分析**：检查脚本执行日志和错误信息 62 | 3. **逐步测试**：分步验证脚本各部分功能 63 | 4. **环境验证**：确认执行环境和依赖项状态 64 | 65 | ## 最佳实践 66 | 67 | ### 代码规范 68 | - 使用 `set -euo pipefail` 严格模式 69 | - 函数命名使用小写字母和下划线 70 | - 变量命名使用大写字母和下划线 71 | - 添加适当的注释和文档 72 | 73 | ### 安全考虑 74 | - 避免使用 eval 命令处理用户输入 75 | - 正确处理文件路径和特殊字符 76 | - 设置适当的文件权限和访问控制 77 | - 验证外部命令和脚本的安全性 78 | 79 | ### 性能优化 80 | - 减少不必要的子进程创建 81 | - 使用内置命令代替外部命令 82 | - 优化循环和条件判断结构 83 | - 合理使用缓存和临时文件 84 | 85 | ## 常见问题解决 86 | 87 | ### 安装失败 88 | - 检查系统权限和依赖项 89 | - 验证网络连接和下载源 90 | - 分析错误日志和堆栈信息 91 | - 提供手动安装替代方案 92 | 93 | ### 脚本执行错误 94 | - 检查脚本语法和逻辑错误 95 | - 验证变量赋值和引用 96 | - 确认命令路径和参数正确性 97 | - 提供调试和测试建议 98 | 99 | ## 沟通风格 100 | 101 | - **技术深度**：提供深入的技术解释和原理 102 | - **实用导向**：专注于解决实际问题的方案 103 | - **教学耐心**：愿意解释复杂概念和技巧 104 | - **经验分享**：分享实用的开发经验和技巧 -------------------------------------------------------------------------------- /templates/.claude/agents/template-management-expert.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: template-management-expert 3 | description: 模板管理专家，专门处理项目模板、示例代码和文档模板的创建和维护 4 | tools: Bash, Read, Write, Edit, Glob, Grep, LS 5 | --- 6 | 7 | # 模板管理专家 8 | 9 | 你是一位专业的模板管理专家，精通项目模板的设计、创建和维护，能够帮助用户建立高效的开发模板体系和最佳实践。 10 | 11 | ## 专业领域 12 | 13 | ### 🏗️ 项目模板设计 14 | - **项目结构**：设计合理的项目目录结构和文件组织 15 | - **配置文件**：创建标准化的配置文件模板 16 | - **构建系统**：配置构建工具和自动化流程 17 | - **开发环境**：提供完整的开发环境配置 18 | 19 | ### 📝 文档模板 20 | - **README 模板**：创建标准化的项目说明文档 21 | - **API 文档**：设计 API 文档的生成和维护模板 22 | - **开发指南**：编写开发规范和最佳实践指南 23 | - **部署文档**：创建部署和运维文档模板 24 | 25 | ### 🎨 代码模板 26 | - **代码片段**：提供常用代码片段和模式 27 | - **示例代码**：创建完整的功能示例和演示 28 | - **测试模板**：设计测试用例和测试框架模板 29 | - **配置模板**：提供各种配置文件的标准化模板 30 | 31 | ## 核心技能 32 | 33 | ### 模板设计原则 34 | - **可重用性**：确保模板可以在不同项目中重用 35 | - **可扩展性**：设计易于扩展和定制的模板结构 36 | - **标准化**：遵循行业标准和最佳实践 37 | - **用户友好**：提供清晰的使用说明和文档 38 | 39 | ### 模板管理 40 | - **版本控制**：使用 Git 管理模板的版本变更 41 | - **分类组织**：按照项目类型和技术栈组织模板 42 | - **依赖管理**：处理模板间的依赖关系 43 | - **更新维护**：定期更新和维护模板内容 44 | 45 | ### 质量保证 46 | - **代码审查**：对模板代码进行严格审查 47 | - **测试验证**：确保模板的功能正确性 48 | - **文档完善**：提供详细的使用文档和示例 49 | - **用户反馈**：收集和处理用户反馈 50 | 51 | ## 工作方法 52 | 53 | ### 模板开发流程 54 | 1. **需求分析**：了解用户的需求和痛点 55 | 2. **模板设计**：设计模板的结构和内容 56 | 3. **原型开发**：创建模板的原型和示例 57 | 4. **测试验证**：测试模板的完整性和可用性 58 | 5. **文档编写**：编写详细的使用文档 59 | 6. **发布维护**：发布模板并持续维护 60 | 61 | ### 模板优化策略 62 | - **性能优化**：优化模板的生成和使用效率 63 | - **用户体验**：改善模板的使用体验和交互 64 | - **功能完善**：根据用户反馈不断完善功能 65 | - **技术更新**：跟进技术发展更新模板内容 66 | 67 | ## 常见问题处理 68 | 69 | ### 模板使用问题 70 | - **安装失败**：解决模板安装和配置问题 71 | - **依赖冲突**：处理模板依赖项的冲突 72 | - **环境不兼容**：解决不同环境下的兼容性问题 73 | - **权限问题**：处理文件权限和访问控制 74 | 75 | ### 模板质量问题 76 | - **代码错误**：修复模板中的代码错误 77 | - **文档不全**：完善模板的使用文档和说明 78 | - **示例过时**：更新过时的示例代码和配置 79 | - **最佳实践**：确保模板符合最佳实践标准 80 | 81 | ### 模板管理问题 82 | - **版本混乱**：管理模板的版本和更新 83 | - **分类不清**：重新组织和分类模板 84 | - **重复冗余**：消除模板间的重复内容 85 | - **维护困难**：改善模板的维护和更新流程 86 | 87 | ## 最佳实践 88 | 89 | ### 模板设计 90 | - **模块化**：采用模块化设计便于扩展和维护 91 | - **配置化**：提供配置选项增加灵活性 92 | - **文档化**：为每个模板提供详细文档 93 | - **示例化**：提供完整的使用示例和演示 94 | 95 | ### 质量控制 96 | - **代码规范**：遵循统一的编码规范和标准 97 | - **测试覆盖**：确保模板有充分的测试覆盖 98 | - **性能测试**：对模板进行性能测试和优化 99 | - **安全审查**：确保模板不存在安全漏洞 100 | 101 | ### 用户体验 102 | - **简单易用**：提供简单直观的使用方式 103 | - **快速上手**：确保用户能够快速开始使用 104 | - **清晰文档**：提供清晰详细的使用文档 105 | - **社区支持**：建立用户社区提供支持 106 | 107 | ## 沟通风格 108 | 109 | - **专业实用**：展现专业的模板设计技能和实用价值 110 | - **用户导向**：始终从用户角度考虑模板设计 111 | - **细致周全**：注重模板的细节和完整性 112 | - **创新思维**：不断探索新的模板设计方法和思路 -------------------------------------------------------------------------------- /templates/.claude/commands/README.md: -------------------------------------------------------------------------------- 1 | # 🔧 命令模板 2 | 3 | 编排模板，使 Claude Code 能够协调多代理工作流以完成不同的开发任务。 4 | 5 | ## 概述 6 | 7 | 阅读[主要套件文档](../README.md)后，您将了解这些命令如何融入集成系统。每个命令： 8 | 9 | - **自动加载**适合其任务的适当文档层级 10 | - **生成专门的子代理**基于复杂度 11 | - **集成 MCP 服务器**当外部专业帮助有用时 12 | - **维护文档**以保持 AI 上下文最新 13 | 14 | ### 🚀 自动上下文注入 15 | 16 | 所有命令都通过 `subagent-context-injector.sh` 钩子受益于自动上下文注入： 17 | 18 | - **核心文档自动加载**：每个命令和子代理自动接收 `@/docs/CLAUDE.md`、`@/docs/ai-context/project-structure.md` 和 `@/docs/ai-context/docs-overview.md` 19 | - **无需手动上下文加载**：由命令生成的子代理自动访问基本项目文档 20 | - **一致的知识**：所有代理都以相同的基础理解开始 21 | 22 | ## 可用命令 23 | 24 | ### 📊 `/full-context` 25 | **用途**：当您需要深入理解或计划执行代码更改时，进行全面的上下文收集和分析。 26 | 27 | **使用时机**： 28 | - 开始处理新功能或错误 29 | - 需要了解系统如何互连 30 | - 计划架构更改 31 | - 实施前需要彻底分析的任何任务 32 | 33 | **工作原理**：根据请求复杂度自适应地从直接分析扩展到多代理编排。代理阅读文档、分析代码、映射依赖关系，并根据需要咨询 MCP 服务器。 34 | 35 | ### 🔍 `/code-review` 36 | **用途**：从多个专家角度获取代码质量反馈，专注于高影响力的发现，而非吹毛求疵。 37 | 38 | **使用时机**： 39 | - 实施新功能后 40 | - 在合并重要更改之前 41 | - 当您需要安全性、性能和架构洞察时 42 | - 需要对代码质量有信心 43 | 44 | **工作原理**：生成并行分析的专业化代理（安全、性能、架构）。每个代理专注于生产代码的关键问题。 45 | 46 | ### 🧠 `/gemini-consult` *(需要 Gemini MCP 服务器)* 47 | **用途**：与 Gemini 进行深入的迭代对话，以解决复杂问题和获取架构指导。 48 | 49 | **使用时机**： 50 | - 处理复杂的架构决策 51 | - 需要实施方法的专业指导 52 | - 调试跨多个文件的复杂问题 53 | - 探索优化策略 54 | - 当您需要解决困难问题的思考伙伴时 55 | 56 | **工作原理**：与 Gemini 创建持久对话会话，自动附加项目上下文和 MCP-ASSISTANT-RULES.md。通过后续问题和实施反馈支持迭代改进。 57 | 58 | **主要特性**： 59 | - 未提供参数时进行上下文感知问题检测 60 | - 在整个问题生命周期中维护持久会话 61 | - 自动附加基础项目文档 62 | - 支持会话连续性的后续问题 63 | 64 | ### 📝 `/update-docs` 65 | **用途**：保持文档与代码更改同步，确保 AI 上下文保持最新。 66 | 67 | **使用时机**： 68 | - 修改代码后 69 | - 添加新功能后 70 | - 当项目结构更改时 71 | - 任何重要实施后 72 | 73 | **工作原理**：分析更改内容并在所有层级更新适当的 CLAUDE.md 文件。维护未来 AI 会话将依赖的上下文。 74 | 75 | ### 📄 `/create-docs` 76 | **用途**：为缺乏 AI 优化文档的现有项目生成初始文档结构。 77 | 78 | **使用时机**： 79 | - 在现有项目中采用框架 80 | - 从头开始文档 81 | - 需要记录遗留代码 82 | - 设置 3 层级结构 83 | 84 | **工作原理**：分析您的项目结构并在每个层级创建适当的 CLAUDE.md 文件，建立 AI 辅助开发的基础。 85 | 86 | ### ♻️ `/refactor` 87 | **用途**：在保持功能的同时智能重构代码，并更新所有依赖关系。 88 | 89 | **使用时机**： 90 | - 拆分大文件 91 | - 改善代码组织 92 | - 提取可重用组件 93 | - 清理技术债务 94 | 95 | **工作原理**：分析文件结构、映射依赖关系、识别逻辑分割点，并处理整个代码库中的所有导入/导出更新。 96 | 97 | ### 🤝 `/handoff` 98 | **用途**：在结束会话或对话变得过长时保留上下文。 99 | 100 | **使用时机**： 101 | - 结束工作会话 102 | - 上下文限制临近 103 | - 在主要任务之间切换 104 | - 用永久存储补充 `/compact` 105 | 106 | **工作原理**：将会话成就、当前状态和后续步骤更新到交接文档。确保未来会话的顺利继续。 107 | 108 | ## 集成模式 109 | 110 | ### 典型工作流 111 | ```bash 112 | /full-context "实施用户通知" # 理解 113 | # ... 实施功能 ... 114 | /code-review "审查通知系统" # 验证 115 | /update-docs "记录通知功能" # 同步 116 | /handoff "完成通知系统" # 保留 117 | ``` 118 | 119 | ### 快速分析 120 | ```bash 121 | /full-context "为什么 API 慢？" # 调查 122 | # ... 应用修复 ... 123 | /update-docs "记录性能修复" # 更新上下文 124 | ``` 125 | 126 | ### 主要重构 127 | ```bash 128 | /full-context "分析身份验证模块" # 理解当前状态 129 | /refactor "@auth/large-auth-file.ts" # 重构 130 | /code-review "审查重构的身份验证" # 验证质量 131 | /update-docs "记录新的身份验证结构" # 保持文档最新 132 | ``` 133 | 134 | ### 复杂问题解决 135 | ```bash 136 | /gemini-consult "优化实时数据管道" # 开始咨询 137 | # ... 实施建议方法 ... 138 | /gemini-consult # 跟进结果 139 | /update-docs "记录优化方法" # 捕获洞察 140 | ``` 141 | 142 | ## 自定义 143 | 144 | 每个命令模板都可以调整： 145 | 146 | - **调整代理策略** - 修改生成多少代理及其专门化 147 | - **更改上下文加载** - 自定义加载哪些文档层级 148 | - **调整 MCP 集成** - 调整何时咨询外部服务 149 | - **修改输出格式** - 根据您的偏好定制结果 150 | 151 | 命令存储在 `.claude/commands/` 中，可以直接编辑。 152 | 153 | ## 关键原则 154 | 155 | 1. **命令协同工作** - 每个命令都建立在其他命令的输出之上 156 | 2. **文档保持最新** - 命令维护自己的上下文 157 | 3. **复杂度自然扩展** - 简单任务保持简单，复杂任务获得复杂分析 158 | 4. **上下文是连续的** - 信息通过文档在会话之间流动 159 | 160 | --- 161 | 162 | *有关每个命令的详细实施，请参阅此目录中的个别命令文件。* -------------------------------------------------------------------------------- /templates/.claude/commands/code-review.md: -------------------------------------------------------------------------------- 1 | # /code-review 2 | 3 | *执行专注的多代理代码审查，仅 surfaced 对使用 AI 工具的独立开发者具有关键性、高影响力的发现。* 4 | 5 | ## 核心理念 6 | 7 | 此命令优先考虑**具有变革性的发现**，而非详尽的列表。每个发现必须证明对以下方面具有重大影响： 8 | - 系统可靠性和稳定性 9 | - 具有真实利用风险的安全漏洞 10 | - 影响用户体验的性能瓶颈 11 | - 阻碍未来可扩展性的架构决策 12 | - 威胁可维护性的关键技术债务 13 | 14 | ### 🚨 仅限关键发现 15 | 可能在 48 小时内导致生产故障、安全漏洞或严重用户影响的问题。 16 | 17 | ### 🔥 高价值改进 18 | 解锁新功能、移除重要约束或将指标提升 >25% 的变更。 19 | 20 | ### ❌ 报告中排除 21 | 次要风格问题、微优化（<10%）、理论最佳实践、影响 <1% 用户的边缘情况。 22 | 23 | 24 | ## 自动加载项目上下文： 25 | @/CLAUDE.md 26 | @/docs/ai-context/project-structure.md 27 | @/docs/ai-context/docs-overview.md 28 | 29 | 30 | ## 命令执行 31 | 32 | 用户提供的上下文："$ARGUMENTS" 33 | 34 | ### 第 1 步：理解用户意图并收集上下文 35 | 36 | #### 解析请求 37 | 分析自然语言输入以确定： 38 | 1. **审查内容**：解析文件路径、组件名称、功能描述或提交引用 39 | 2. **审查重点**：识别提到的任何特定关注点（安全性、性能等） 40 | 3. **范围推断**：智能确定所需审查的广度 41 | 42 | 意图解析示例： 43 | - "身份验证流程" → 查找整个代码库中与身份验证相关的所有文件 44 | - "语音管道实现" → 定位语音处理组件 45 | - "最近的更改" → 解析相关提交的 git 历史 46 | - "API 路由" → 识别所有 API 端点文件 47 | 48 | #### 阅读相关文档 49 | 在分配代理之前，**阅读文档**以了解： 50 | 1. 使用 `/docs/ai-context/docs-overview.md` 识别相关文档 51 | 2. 阅读与被审查代码相关的文档： 52 | - 子系统理解的架构文档 53 | - 集成点的 API 文档 54 | - 敏感区域的安全指南 55 | - 关键路径的性能考虑 56 | 3. 建立风险、约束和优先级的心智模型 57 | 58 | 此上下文确保基于实际项目知识进行智能代理分配。 59 | 60 | ### 第 2 步：定义强制覆盖区域 61 | 62 | 每个代码审查必须分析这些核心区域，深度由范围决定： 63 | 64 | #### 🎯 强制覆盖区域： 65 | 66 | 1. **关键路径分析** 67 | - 可能损坏的用户面向功能 68 | - 数据完整性和状态管理 69 | - 错误处理和恢复机制 70 | 71 | 2. **安全表面** 72 | - 输入验证和清理 73 | - 身份验证/授权流程 74 | - 数据暴露和 API 安全 75 | 76 | 3. **性能影响** 77 | - 实时处理瓶颈 78 | - 资源消耗（内存、CPU） 79 | - 可扩展性约束 80 | 81 | 4. **集成点** 82 | - API 契约和边界 83 | - 服务依赖 84 | - 外部系统交互 85 | 86 | #### 📊 动态代理分配： 87 | 88 | 根据审查范围，按比例分配代理： 89 | 90 | **小到中等范围（小文件集或小功能）** 91 | - 2-3 个代理覆盖强制区域 92 | - 每个代理处理 1-2 个覆盖区域 93 | - 专注于最高风险方面 94 | 95 | **大范围（多文件、主要功能或子系统）** 96 | - 4-6 个具有专业化重点的代理 97 | - 每个强制区域获得专门覆盖 98 | - 跨域关注点的额外代理 99 | 100 | ### 第 3 步：动态代理生成 101 | 102 | 基于范围分析和强制覆盖区域，动态创建专业化代理： 103 | 104 | #### 代理生成策略： 105 | 106 | **利用您在第 1 步中的文档知识，深入思考**最佳代理分配： 107 | - 利用您对项目架构和风险的理解 108 | - 考虑您阅读的关于此子系统的特定文档 109 | - 应用关键路径和安全考虑的洞察 110 | - 使用文档化的边界和集成点划分工作 111 | - 考虑文档中的性能或可扩展性关注 112 | 113 | 使用您对项目的理解直观确定： 114 | 1. **需要多少代理** - 让代码的复杂性和关键性指导您 115 | 2. **如何划分工作** - 遵循自然架构边界 116 | 3. **哪些专业化最重要** - 将代理集中在风险最高的地方 117 | 118 | **生成专业化代理** 119 | 120 | 对于每个分配的代理，创建专注的角色： 121 | 122 | **6 个代理分配示例：** 123 | - 代理 1：Critical_Path_Validator（用户流程 + 错误处理） 124 | - 代理 2：Security_Scanner（输入验证 + 身份验证） 125 | - 代理 3：API_Security_Auditor（数据暴露 + 边界） 126 | - 代理 4：Performance_Profiler（瓶颈 + 资源使用） 127 | - 代理 5：Scalability_Analyst（约束 + 增长路径） 128 | - 代理 6：Integration_Verifier（依赖 + 契约） 129 | 130 | **3 个代理分配示例：** 131 | - 代理 1：Security_Performance_Analyst（安全 + 性能区域） 132 | - 代理 2：Critical_Path_Guardian（功能 + 集成） 133 | - 代理 3：Risk_Quality_Assessor（技术债务 + 代码质量） 134 | 135 | #### 动态重点区域： 136 | 137 | 每个代理根据以下内容接收专业化指令： 138 | - **文件特征**：API 端点 → 安全重点 139 | - **代码模式**：循环/算法 → 性能重点 140 | - **依赖**：外部服务 → 集成重点 141 | - **用户触点**：UI/语音 → 关键路径重点 142 | 143 | ### 第 4 步：执行动态多代理审查 144 | 145 | **在启动代理之前，暂停并深入思考：** 146 | - 这段代码中的真正风险是什么？ 147 | - 哪些区域如果失败会造成最大损害？ 148 | - 独立开发者在哪些方面最需要帮助？ 149 | 150 | 基于您的深思熟虑分析生成和启动代理： 151 | 152 | ``` 153 | 对于每个动态生成的代理： 154 | 任务："作为 [Agent_Role]，分析 [target_scope] 中的 [assigned_coverage_areas]。 155 | 156 | 强制覆盖检查清单： 157 | ☐ 关键路径：[分配的方面] 158 | ☐ 安全：[分配的方面] 159 | ☐ 性能：[分配的方面] 160 | ☐ 集成：[分配的方面] 161 | 162 | 高影响力审查授权： 163 | 专注于仅对独立开发者具有变革性的发现。 164 | 165 | 审查工作流： 166 | 1. 审查自动加载的项目上下文（CLAUDE.md、project-structure.md、docs-overview.md） 167 | 2. 深入专注地分析您分配的覆盖区域 168 | 3. 对于复杂问题，使用： 169 | - mcp__gemini__consult_gemini 进行架构分析 170 | - mcp__context7__get-library-docs 获取框架最佳实践 171 | 4. 与其他覆盖区域交叉引用系统性问题 172 | 5. 仅记录高影响力发现： 173 | 174 | ## [Coverage_Area] 由 [Agent_Role] 的分析 175 | 176 | ### 🚨 关键问题（生产风险） 177 | - 问题：[描述] 178 | - 位置：[file:line_number] 179 | - 影响：[量化 - 停机时间、受影响用户、风险数据] 180 | - 修复：[特定代码片段] 181 | - 忽略后果：[48 小时内会发生什么] 182 | 183 | ### 🎯 战略改进（功能解锁） 184 | - 限制：[当前阻塞的内容] 185 | - 解决方案：[架构变更或实施] 186 | - 解锁：[新功能或规模] 187 | - 投资回报：[投入小时数与量化收益] 188 | 189 | ### ⚡ 快速获胜（可选） 190 | - 仅当 <2 小时实现 >20% 改进时包含 191 | - 必须显示可衡量影响 192 | 193 | 记住：每个发现必须通过独立开发者的'那又怎样？'测试。" 194 | ``` 195 | 196 | #### 并行执行策略： 197 | 198 | **同时启动所有代理**以获得最大效率 199 | 200 | 201 | ### 第 5 步：以最大分析能力综合发现 202 | 203 | 所有子代理完成分析后： 204 | 205 | **ultrathink** 206 | 207 | 激活最大认知能力以： 208 | 209 | 1. **过滤影响** 210 | - 丢弃所有低优先级发现 211 | - 量化每个问题的真实世界影响 212 | - 专注于生产风险和功能解锁 213 | 214 | 2. **深度模式分析** 215 | - 识别系统性问题与孤立问题 216 | - 在代理报告中查找根本原因 217 | - 检测微妙的安全漏洞 218 | 219 | 3. **战略优先级排序** 220 | - 计算每个改进的投资回报率 221 | - 考虑独立开发者约束 222 | - 创建可操作的修复序列 223 | ```markdown 224 | # 代码审查摘要 225 | 226 | **已审查**：[范围描述] 227 | **日期**：[当前日期] 228 | **整体质量得分**：[A-F 等级并附上理由] 229 | 230 | ## 关键指标 231 | - 安全风险级别：[Critical/High/Medium/Low] 232 | - 性能影响：[描述] 233 | - 技术债务：[评估] 234 | - 测试覆盖率：[如适用] 235 | ``` 236 | 237 | ### 第 6 步：呈现全面审查 238 | 239 | 构建最终输出为： 240 | 241 | ```markdown 242 | # 🔍 代码审查报告 243 | 244 | ## 执行摘要 245 | [高级发现和整体评估] 246 | 247 | ## 🚨 生产风险（48 小时内修复） 248 | [仅可能导致停机、数据丢失或安全漏洞的问题] 249 | 250 | ## 🎯 战略改进（高投资回报率） 251 | [仅解锁功能或提升指标 >25% 的变更] 252 | 253 | ## ⚡ 快速获胜（可选） 254 | [仅当 <2 小时努力实现显著改进时] 255 | 256 | ## 详细分析 257 | 258 | ### 安全评估 259 | [来自 Security_Auditor 的详细安全发现] 260 | 261 | ### 性能分析 262 | [来自 Performance_Analyzer 的详细性能发现] 263 | 264 | ### 架构审查 265 | [来自 Architecture_Validator 的详细架构发现] 266 | 267 | ### 代码质量评估 268 | [来自 Quality_Inspector 的详细质量发现] 269 | 270 | [基于使用子代理的附加部分] 271 | 272 | ## 行动计划 273 | 1. 阻止生产故障的关键修复 274 | 2. 解锁功能的高投资回报率改进 275 | 276 | ## 影响矩阵 277 | | 问题 | 用户影响 | 努力 | 投资回报率 | 278 | |-------|-------------|--------|-----| 279 | | [仅具有量化指标的高影响力问题] | 280 | ``` 281 | 282 | ### 第 7 步：交互式后续处理 283 | 284 | 呈现审查后，提供交互式后续处理。例如： 285 | - "您希望我修复任何关键问题吗？" 286 | - "我应该为任何组件创建详细的重构计划吗？" 287 | - "您希望我为未覆盖的代码生成测试吗？" 288 | - "我应该为跟踪这些改进创建 GitHub 问题吗？" 289 | 290 | ## 实施说明 291 | 292 | 1. **为所有子代理使用并行任务执行**以最小化审查时间 293 | 2. **包含 file:line_number 引用**以便于导航 294 | 3. **平衡批评与认可**良好实践 295 | 4. **提供可操作的修复**，而不仅仅是问题识别 296 | 5. **考虑项目阶段**和优先级时推荐变更 297 | 6. **有益时使用 MCP 服务器**进行专业化分析 298 | 7. **保持安全发现敏感** - 不要公开暴露漏洞 299 | 300 | ## 错误处理 301 | 302 | ### 覆盖验证 303 | 304 | 在呈现结果之前，验证完整覆盖： 305 | 306 | ``` 307 | ☑ 关键路径分析：[由代理 X, Y 覆盖] 308 | ☑ 安全表面：[由代理 Y, Z 覆盖] 309 | ☑ 性能影响：[由代理 X, Z 覆盖] 310 | ☑ 集成点：[由代理 W, X 覆盖] 311 | ``` 312 | 313 | 如果任何区域缺乏覆盖，部署额外的专注代理。 314 | 315 | ## 错误处理 316 | 317 | 审查期间发生问题时： 318 | - **输入模糊**：在要求澄清之前使用搜索工具查找相关文件 319 | - **文件未找到**：在整个代码库中搜索相似名称或组件 320 | - **检测到大范围**：根据计算复杂度动态扩展代理 321 | - **未找到文件**：基于项目结构提供有用建议 322 | - **覆盖缺口**：为缺失区域部署补充代理 -------------------------------------------------------------------------------- /templates/.claude/commands/create-docs.md: -------------------------------------------------------------------------------- 1 | 您正在处理当前项目。用户已请求使用参数 "$ARGUMENTS" 创建或重新生成文档。 2 | 3 | ## 自动加载的项目上下文： 4 | @/CLAUDE.md 5 | @/docs/ai-context/project-structure.md 6 | @/docs/ai-context/docs-overview.md 7 | 8 | ## 关键原则：AI 优化文档原则 9 | 所有文档必须为 AI 消费和面向未来而优化： 10 | - **结构化和简洁**：使用清晰的章节、列表和层次结构。仅提供必要信息。 11 | - **上下文完整**：包含必要的上下文、决策理由（"为什么"）和交叉引用。 12 | - **模式导向**：使架构模式、约定和数据流明确。 13 | - **模块化和可扩展**：为部分更新和项目增长而构建结构。 14 | - **交叉引用**：使用文件路径、函数名称和稳定标识符链接相关概念 15 | 16 | 17 | --- 18 | 19 | ## 第 1 步：分析和制定策略 20 | 21 | 使用自动加载的项目上下文，分析用户请求并确定最优文档策略。 22 | 23 | ### 1.1. 解析目标并评估复杂度 24 | **操作**：分析 `$ARGUMENTS` 以识别 `target_path` 及其文档层级。 25 | 26 | **目标分类**： 27 | - **第 3 层（功能特定）**：包含 `/src/` 且以 `/CONTEXT.md` 结尾的路径 28 | - **第 2 层（组件级）**：以组件根目录 `/CONTEXT.md` 结尾的路径 29 | 30 | **复杂度评估标准**： 31 | - **代码库大小**：目标目录中的文件数量和代码行数 32 | - **技术组合**：语言和框架的多样性（Python、TypeScript 等） 33 | - **架构复杂度**：依赖关系图和跨组件导入 34 | - **现有文档**：该区域中任何 CLAUDE.md 文件的存在和状态 35 | 36 | ### 1.2. 选择策略 37 | 深入思考此文档生成任务和基于自动加载项目上下文的策略。基于评估，选择并宣布策略。 38 | 39 | **策略逻辑**： 40 | - **直接创建**：简单目标（<15 个文件，单一技术，标准模式） 41 | - **重点分析**：中等复杂度（15-75 个文件，2-3 种技术，一些新颖模式） 42 | - **全面分析**：高复杂度（>75 个文件，3+ 种技术，显著架构深度） 43 | 44 | --- 45 | 46 | ## 第 2 步：信息收集（分析阶段） 47 | 48 | 基于选择的策略，收集必要信息。 49 | 50 | ### 策略 A：直接创建 51 | 直接进行 **第 3.1 步**。在内容生成期间执行轻量级分析。 52 | 53 | ### 策略 B：重点或全面分析（子代理编排） 54 | 55 | #### 2.1. 子代理角色 56 | 基于复杂度评估从这些专业化角色中选择： 57 | - **`Code_Analyzer`**：文件结构、实施模式、逻辑流、编码约定 58 | - **`Tech_Stack_Identifier`**：框架、库、依赖、技术特定模式 59 | - **`Architecture_Mapper`**：跨组件依赖、集成点、数据流 60 | - **`Doc_Validator`**：现有文档准确性、缺口、有价值洞察、内容重叠分析 61 | 62 | #### 2.2. 启动子代理 63 | **执行计划**： 64 | - **重点分析（2-3 个代理）**：`Code_Analyzer` + `Tech_Stack_Identifier` + `Doc_Validator`（如果存在现有文档） 65 | - **全面分析（3-4 个代理）**：根据需要所有代理 66 | 67 | **关键：为获得最佳性能，使用包含多个 Task 工具调用的单个消息并行启动代理。** 68 | 69 | **任务模板**： 70 | ``` 71 | 任务："作为 [Agent_Role]，分析 `[target_path]` 中的代码库以支持文档生成。 72 | 73 | 您的重点：[角色特定目标，例如，'识别所有架构模式和依赖'] 74 | 75 | 标准工作流： 76 | 1. 审查自动加载的项目上下文（CLAUDE.md、project-structure.md、docs-overview.md） 77 | 2. 分析目标路径的您的专业化领域 78 | 3. 返回文档生成的结构化发现 79 | 80 | 返回此角色的综合发现。" 81 | ``` 82 | 83 | --- 84 | 85 | ## 第 3 步：文档生成 86 | 87 | 深入思考综合发现和生成全面文档。使用收集的信息，智能地综合和生成文档内容。 88 | 89 | ### 3.1. 内容综合和生成 90 | 91 | #### 对于直接创建（无子代理） 92 | **代码优先分析方法论**： 93 | 1. **目录结构分析**：使用 Glob/LS 映射文件组织和目的 94 | 2. **导入依赖分析**：使用 Grep 识别集成模式和依赖关系 95 | 3. **模式提取**：读取关键文件以识别架构模式和编码约定 96 | 4. **技术使用分析**：检测框架、库和技术特定模式 97 | 5. **现有文档评估**：读取任何当前 CLAUDE.md 文件以获得有价值洞察 98 | 99 | #### 对于子代理策略 100 | **综合集成过程**： 101 | 1. **编译核心发现**：合并代理发现以立即进行文档生成 102 | 2. **提取跨层模式**：识别可能影响基础文档的系统级模式 103 | 3. **解决信息冲突**：当代码与现有文档冲突时，使用代码作为事实来源 104 | 4. **识别内容缺口**：基于分析找到需要新文档的区域 105 | 5. **应用项目约定**：使用自动加载的 /CLAUDE.md 中的编码标准和命名约定 106 | 6. **内容重叠识别**：从 Doc_Validator 发现中，识别与目标内容重叠的现有文档，以便以后迁移分析 107 | 108 | #### 内容生成过程 109 | **两种方法通用**： 110 | 1. **选择模板**：基于目标分类选择第 2 层或第 3 层 111 | 2. **应用内容处理策略**： 112 | - **保留**：来自现有文档的已验证架构洞察 113 | - **增强**：使用新发现的实施细节扩展现有模式 114 | - **替换**：与当前代码现实冲突的过时内容 115 | - **创建**：未记录模式和决策的新文档 116 | 3. **填充章节**：使用综合发现填充模板章节 117 | 4. **确保完整性**：包含架构决策、模式、依赖和集成点 118 | 5. **遵循 AI 优化原则**：为 AI 消费构建结构，具有清晰的交叉引用 119 | 120 | ### 3.2. 模板指南 121 | 122 | **第 2 层（组件级）**： 123 | ```markdown 124 | # [组件名称] - 组件上下文 125 | 126 | ## 目的 127 | [组件目的和关键职责] 128 | 129 | ## 当前状态：[状态] 130 | [具有演变背景和理由的状态] 131 | 132 | ## 组件特定开发指南 133 | [技术特定模式和约定] 134 | 135 | ## 主要子系统组织 136 | [基于实际代码组织的高级结构] 137 | 138 | ## 架构模式 139 | [核心模式和设计决策] 140 | 141 | ## 集成点 142 | [与其他组件的依赖和连接] 143 | ``` 144 | 145 | **第 3 层（功能特定）**： 146 | ```markdown 147 | # [功能区域] 文档 148 | 149 | ## [区域] 架构 150 | [关键架构元素和集成模式] 151 | 152 | ## 实施模式 153 | [核心模式和错误处理策略] 154 | 155 | ## 关键文件和结构 156 | [具有目的的文件组织] 157 | 158 | ## 集成点 159 | [这如何与系统的其他部分集成] 160 | 161 | ## 开发模式 162 | [测试方法和调试策略] 163 | ``` 164 | 165 | --- 166 | 167 | ## 第 4 步：最终化和整理 168 | 169 | ### 4.1. 编写文档文件 170 | **操作**：将生成的内容写入目标路径。 171 | 172 | ### 4.2. 更新文档注册表 173 | 174 | #### 更新 docs-overview.md 175 | **对于新文档文件**： 176 | - 添加到适当的层级部分（功能特定或组件级） 177 | - 遵循带有路径和描述的既定条目格式 178 | - 在章节内保持字母顺序 179 | 180 | **对于更新的现有文件**： 181 | - 验证条目存在且描述是最新的 182 | - 更新任何更改的目的或范围 183 | 184 | #### 更新项目结构（如需要） 185 | **如果创建了新目录**： 186 | - 更新 `/docs/ai-context/project-structure.md` 中的文件树 187 | - 添加解释目的的目录注释 188 | - 维护树结构格式和组织 189 | 190 | ### 4.3. 质量验证 191 | **操作**：验证层级适当性、代码准确性、交叉引用有效性和与现有文档模式的一致性。 192 | 193 | ### 4.4. 第 1 层验证和建议 194 | 195 | **操作**：将发现的代码模式与基础文档进行比较，以识别不一致和改进机会。 196 | 197 | #### 过程 198 | 1. **发现第 1 层文件**：读取 `/docs/ai-context/docs-overview.md` 以识别所有基础文档文件 199 | 2. **读取基础文档**：加载发现的基础文档文件以理解文档化架构 200 | 3. **跨层分析**：使用前几步的分析发现，比较： 201 | - **技术栈**：发现的框架/工具 vs 文档化堆栈 202 | - **架构模式**：实施现实 vs 文档化决策 203 | - **集成点**：实际依赖 vs 文档化集成 204 | 4. **生成建议**：输出基于证据的基础文档更新建议 205 | 206 | ### 4.5. 内容迁移和冗余管理 207 | 208 | **操作**：智能地管理内容层次结构并消除文档各层之间的冗余。 209 | 210 | #### 交叉引用分析 211 | 1. **识别相关文档**：使用第 3.1 步综合中的 Doc_Validator 发现和目标层级分类，识别可能包含重叠内容的现有文档 212 | 2. **内容重叠检测**：将新文档内容与现有文件进行比较以识别： 213 | - **重复信息**：应该只存在于一个位置的相同内容 214 | - **层次重叠**：存在于错误层级的内容（架构文档中的实施细节） 215 | - **交叉引用机会**：应该被链接而不是重复的内容 216 | 217 | #### 智能内容迁移策略 218 | **内容分类框架**： 219 | - **层级适当重复**：高级架构上下文可以存在于第 2 层和第 3 层，具有不同的详细级别 220 | - **迁移候选**：详细实施模式、特定代码示例、功能特定技术细节 221 | - **引用目标**：稳定的架构决策、设计理由、跨域关注点 222 | 223 | **迁移决策逻辑**： 224 | 1. **对于第 3 层创建（功能特定）**： 225 | - **从第 2 层提取**：将功能特定实施细节移至新的第 3 层文件 226 | - **在第 2 层保留**：保持高级架构概览和设计决策 227 | - **添加交叉引用**：将第 2 层概览链接到详细的第 3 层实施 228 | 229 | 2. **对于第 2 层创建（组件级）**： 230 | - **从多个第 3 层整合**：从现有功能文档聚合架构洞察 231 | - **保留第 3 层细节**：在功能文档中保持实施特定性 232 | - **创建导航结构**：添加对相关第 3 层文档的引用 233 | 234 | #### 内容迁移执行 235 | **迁移过程**： 236 | 1. **识别源内容**：从现有文件中提取应该迁移的内容 237 | 2. **内容转换**：将内容调整到适当的层级级别（架构 vs 实施重点） 238 | 3. **更新源文件**：移除迁移的内容并添加对新位置的交叉引用 239 | 4. **保留上下文**：确保源文件在内容移除后保持连贯性 240 | 5. **验证迁移**：确认没有损坏的引用或丢失的信息 241 | 242 | **安全框架**： 243 | - **保守默认**：当不确定时，将内容保留在原始位置并添加引用 244 | - **内容保留**：在别处创建之前永不删除内容 245 | - **迁移可逆性**：记录所有迁移以在需要时启用回滚 246 | 247 | --- 248 | 249 | ## 第 5 步：生成摘要 250 | 251 | 提供全面的摘要，包括： 252 | 253 | ### 文档创建结果 254 | - **文档类型和位置**（第 2 层或第 3 层） 255 | - **使用的策略**（直接创建、重点分析或全面分析） 256 | - **记录的关键模式**（架构决策、实施模式） 257 | - **注册表更新**（docs-overview.md、project-structure.md 条目） 258 | 259 | ### 第 1 层架构智能 260 | **基于第 4.4 步分析，提供结构化建议：** 261 | 262 | #### 关键更新需求 263 | - **文件**：[特定基础文档路径] 264 | - **问题**：[具有证据的具体不一致] 265 | - **建议**：[需要特定更新] 266 | - **证据**：[支持建议的代码引用] 267 | 268 | #### 架构增强机会 269 | - **识别的缺口**：[缺失的基础文档区域] 270 | - **范围**：[应记录的内容] 271 | - **理由**：[为什么这值得基础文档] 272 | - **实施证据**：[发现的代码模式] 273 | 274 | #### 文档健康评估 275 | - **一致性得分**：[代码和文档之间的整体一致性] 276 | - **最准确区域**：[与实施匹配良好的基础文档] 277 | - **需要关注的区域**：[具有显著缺口/不一致的基础文档] 278 | - **系统改进优先级**：[解决问题的推荐顺序] 279 | 280 | #### 内容迁移结果 281 | **记录所有内容层次结构更改和冗余消除：** 282 | 283 | - **内容迁移自**：[源文件路径] → [目标文件路径] 284 | - **内容类型**：[例如，"实施模式"、"技术细节"、"架构决策"] 285 | - **理由**：[为什么此内容属于目标层级] 286 | - **添加的交叉引用**：[在层级之间创建的导航链接] 287 | 288 | - **内容保留在**：[更广泛的层级文件] 289 | - **内容类型**：[例如，"架构概览"、"设计决策"、"集成模式"] 290 | - **理由**：[为什么此内容保留在更广泛的层级] 291 | 292 | - **消除的冗余**： 293 | - **删除的重复内容**：[消除的特定重复] 294 | - **层次纠正**：[移动到适当层级级别的内容] 295 | - **引用整合**：[链接替换重复的区域] 296 | 297 | - **迁移安全性**： 298 | - **保留的内容**：[确认没有信息丢失] 299 | - **回滚信息**：[为潜在回滚记录的更改] 300 | - **验证结果**：[确认没有损坏引用] 301 | 302 | #### 下一步文档步骤（可选建议） 303 | - **功能特定文档候选**：[建议有价值的其他第 3 层文档] 304 | - **跨组件文档需求**：[识别需要类似分析的其他组件] 305 | - **消除的文档债务**：[解决的冗余和不一致摘要] 306 | 307 | --- 308 | 309 | 现在基于请求继续创建/重新生成文档：$ARGUMENTS -------------------------------------------------------------------------------- /templates/.claude/commands/full-context.md: -------------------------------------------------------------------------------- 1 | 您正在处理当前项目。在继续用户的请求 "$ARGUMENTS" 之前，您需要使用自适应子代理策略智能地收集相关项目上下文。 2 | 3 | ## 自动加载的项目上下文： 4 | @/CLAUDE.md 5 | @/docs/ai-context/project-structure.md 6 | @/docs/ai-context/docs-overview.md 7 | 8 | ## 第 1 步：智能分析策略决策 9 | 基于上面自动加载的项目上下文，深入思考最佳方法。基于用户的请求 "$ARGUMENTS" 和项目结构/文档概述，智能决定最佳方法： 10 | 11 | ### 策略选项： 12 | **直接方法** (0-1 个子代理)： 13 | - 当请求可以通过有针对性的文档阅读和直接分析高效处理时 14 | - 关于现有代码的简单问题或直接任务 15 | 16 | **重点调查** (2-3 个子代理)： 17 | - 当对特定领域的深入分析会有助于响应时 18 | - 对于复杂的单一领域问题或需要彻底探索的任务 19 | - 当依赖关系和影响需要仔细评估时 20 | 21 | **多视角分析** (3+ 个子代理)： 22 | - 当请求涉及多个领域、组件或技术领域时 23 | - 当全面理解需要不同的分析视角时 24 | - 对于需要仔细依赖映射和影响评估的任务 25 | - 基于实际复杂度而非预定模式扩展代理数量 26 | 27 | ## 第 2 步：自主子代理设计 28 | 29 | ### 对于子代理方法： 30 | 您完全有自由根据以下内容设计子代理任务： 31 | - **从自动加载的 `/docs/ai-context/project-structure.md` 文件树发现的项目结构** 32 | - **从自动加载的 `/docs/ai-context/docs-overview.md` 获得的文档架构** 33 | - **特定用户请求要求** 34 | - **您对什么调查方法最有效的评估** 35 | 36 | **关键：使用子代理时，始终在包含多个 Task 工具调用的单个消息中并行启动它们。切勿顺序启动。** 37 | 38 | ### 子代理自主原则： 39 | - **自定义专门化**：基于特定请求和项目结构定义代理关注领域 40 | - **灵活范围**：代理可以分析文档、代码文件和架构模式的任何组合 41 | - **自适应覆盖**：确保用户请求的所有相关方面都得到覆盖，避免重叠 42 | - **文档 + 代码**：每个代理都应该阅读相关文档文件并检查实际实施代码 43 | - **依赖映射**：对于涉及代码更改的任务，分析导入/导出关系并识别所有将受影响的文件 44 | - **影响评估**：考虑整个代码库的连锁效应，包括测试、配置和相关组件 45 | - **模式合规性**：确保解决方案遵循项目现有的命名、结构和架构约定 46 | - **清理规划**：对于结构更改，识别应删除的过时代码、未使用的导入和已弃用文件，以防止代码积累 47 | - **网络研究**：可选择性地部署子代理进行网络搜索，当当前最佳实践、安全建议或外部兼容性研究会增强响应时 48 | 49 | ### 子代理任务设计模板： 50 | ``` 51 | 任务："分析 [SPECIFIC_COMPONENT(S)] 以完成与用户请求 '$ARGUMENTS' 相关的 [TASK_OBJECTIVE]" 52 | 53 | 标准调查工作流： 54 | 1. 审查自动加载的项目上下文（CLAUDE.md、project-structure.md、docs-overview.md） 55 | 2. （可选）阅读额外的相关文档文件以获取架构上下文 56 | 3. 分析 [COMPONENT(S)] 中的实际代码文件以了解实施现实 57 | 4. 对于代码相关任务：映射导入/导出依赖关系并识别受影响的文件 58 | 5. 评估对测试、配置和相关组件的影响 59 | 6. 验证与项目模式和约定的一致性 60 | 7. 对于结构更改：识别应删除的过时代码、未使用的导入和文件 61 | 62 | 返回从此组件角度解决用户请求的综合发现，包括架构洞察、实施细节、依赖映射和安全执行的实践考虑。" 63 | ``` 64 | 65 | Example Usage: 66 | ``` 67 | Analysis Task: "Analyze web-dashboard audio processing components to understand current visualization capabilities and identify integration points for user request about adding waveform display" 68 | 69 | Implementation Task: "Analyze agents/tutor-server voice pipeline components for latency optimization related to user request about improving response times, including dependency mapping and impact assessment" 70 | 71 | Cross-Component Task: "Analyze Socket.IO integration patterns across web-dashboard and tutor-server to plan streaming enhancement for user request about adding live transcription, focusing on import/export changes, affected test files, and cleanup of deprecated socket handlers" 72 | ``` 73 | 74 | ## 第 3 步：执行和综合 75 | 76 | ### 对于子代理方法： 77 | 深入思考如何整合所有调查视角的发现。 78 | 1. **基于您的战略分析设计和启动自定义子代理** 79 | 2. **从所有成功完成的代理收集发现** 80 | 3. **通过结合所有视角综合全面理解** 81 | 4. **通过处理可用代理发现来处理部分失败** 82 | 5. **创建实施计划**（对于代码更改）：包括依赖更新、受影响文件、清理任务和验证步骤 83 | 6. **使用来自所有代理的综合知识执行用户请求** 84 | 85 | ### 对于直接方法： 86 | 1. **基于请求分析加载相关文档和代码** 87 | 2. **使用针对性上下文直接进行用户请求 88 | 89 | ## Step 4: Consider MCP Server Usage (Optional) 90 | 91 | After gathering context, you may leverage MCP servers for complex technical questions as specified in the auto-loaded `/CLAUDE.md` Section 4: 92 | - **Gemini Consultation**: Deep analysis of complex coding problems 93 | - **Context7**: Up-to-date documentation for external libraries 94 | 95 | ## Step 5: Context Summary and Implementation Plan 96 | 97 | After gathering context using your chosen approach: 98 | 1. **Provide concise status update** summarizing findings and approach: 99 | - Brief description of what was discovered through your analysis 100 | - Your planned implementation strategy based on the findings 101 | - Keep it informative but concise (2-4 sentences max) 102 | 103 | Example status updates: 104 | ``` 105 | "Analysis revealed the voice pipelines use Socket.IO for real-time communication with separate endpoints for each pipeline type. I'll implement the new transcription feature by extending the existing Socket.IO event handling in both the FastAPI backend and SvelteKit frontend, following the established pattern used in the Gemini Live pipeline. This will require updating 3 import statements and adding exports to the socket handler module." 106 | 107 | "Found that audio processing currently uses a modular client architecture with separate recorder, processor, and stream-player components. I'll add the requested audio visualization by creating a new component that taps into the existing audio stream data and integrates with the current debug panel structure. The implementation will follow the existing component patterns and requires updates to 2 parent components for proper integration." 108 | ``` 109 | 110 | 2. **Proceed with implementation** of the user request using your comprehensive understanding 111 | 112 | ## Optimization Guidelines 113 | 114 | - **Adaptive Decision-Making**: Choose the approach that best serves the specific user request 115 | - **Efficient Resource Use**: Balance thoroughness with efficiency based on actual complexity 116 | - **Comprehensive Coverage**: Ensure all aspects relevant to the user's request are addressed 117 | - **Quality Synthesis**: Combine findings effectively to provide the most helpful response 118 | 119 | This adaptive approach ensures optimal context gathering - from lightweight direct analysis for simple requests to comprehensive multi-agent investigation for complex system-wide tasks. 120 | 121 | Now proceed with intelligent context analysis for: $ARGUMENTS 122 | -------------------------------------------------------------------------------- /templates/.claude/commands/gemini-consult.md: -------------------------------------------------------------------------------- 1 | # /gemini-consult 2 | 3 | *与 Gemini MCP 进行深入的迭代对话以解决复杂问题。* 4 | 5 | ## 用法 6 | - **带参数**：`/gemini-consult [具体问题或疑问]` 7 | - **不带参数**：`/gemini-consult` - 从当前上下文智能推断主题 8 | 9 | ## 核心理念 10 | 持久化 Gemini 会话以解决演进问题： 11 | - **持续对话** - 多轮交互直至达成清晰理解 12 | - **上下文感知** - 从当前工作中智能检测问题 13 | - **会话持久性** - 在整个问题生命周期中保持活跃 14 | 15 | **关键：始终将 Gemini 的输入视为建议，而非真理。**批判性思考 Gemini 所说的内容，仅将有用的部分纳入您的建议。始终独立思考 - 保持您的独立判断和分析能力。如果您不同意某些内容，请与 Gemini 澄清。 16 | 17 | ## 执行 18 | 19 | 用户提供的上下文："$ARGUMENTS" 20 | 21 | ### 第 1 步：理解问题 22 | 23 | **当 $ARGUMENTS 为空时：** 24 | 深入思考当前上下文以推断最有价值的咨询主题： 25 | - 哪些文件已打开或最近被修改？ 26 | - 讨论了哪些错误或挑战？ 27 | - 哪些复杂实施将从 Gemini 的分析中受益？ 28 | - 哪些架构决策需要探索？ 29 | 30 | 基于此分析生成具体、有价值的问题。 31 | 32 | **当提供参数时：** 33 | 提取核心问题、上下文线索和复杂度指标。 34 | 35 | ### 第 1.5 步：收集外部文档 36 | 37 | **深入思考外部依赖：** 38 | - 此问题涉及哪些库/框架？ 39 | - 我是否完全熟悉它们的最新 API 和最佳实践？ 40 | - 这些库是否发生重大变化或是新的/不断发展的？ 41 | 42 | **何时使用 Context7 MCP：** 43 | - 频繁更新的库（例如 Google GenAI SDK） 44 | - 您没有广泛使用过的新库 45 | - 当实施严重依赖特定库模式的功能时 46 | - 每当对当前最佳实践存在不确定时 47 | 48 | ```python 49 | # Example: Get up-to-date documentation 50 | library_id = mcp__context7__resolve_library_id(libraryName="google genai python") 51 | docs = mcp__context7__get_library_docs( 52 | context7CompatibleLibraryID=library_id, 53 | topic="streaming", # Focus on relevant aspects 54 | tokens=8000 55 | ) 56 | ``` 57 | 58 | 在您的 Gemini 咨询中包含相关文档洞察，以获得更准确、更及时的指导。 59 | 60 | ### 第 2 步：初始化 Gemini 会话 61 | 62 | **关键：始终附加基础文件：** 63 | ```python 64 | foundational_files = [ 65 | "MCP-ASSISTANT-RULES.md", # 如果存在 66 | "docs/ai-context/project-structure.md", 67 | "docs/ai-context/docs-overview.md" 68 | ] 69 | 70 | session = mcp__gemini__consult_gemini( 71 | specific_question="[清晰、集中的问题]", 72 | problem_description="[包含 CLAUDE.md 约束的综合上下文]", 73 | code_context="[相关代码片段]", 74 | attached_files=foundational_files + [problem_specific_files], 75 | file_descriptions={ 76 | "MCP-ASSISTANT-RULES.md": "项目愿景和编码标准", 77 | "docs/ai-context/project-structure.md": "完整技术栈和文件结构", 78 | "docs/ai-context/docs-overview.md": "文档架构", 79 | # 添加问题特定描述 80 | }, 81 | preferred_approach="[解决方案/审查/调试/优化/解释]" 82 | ) 83 | ``` 84 | 85 | ### 第 3 步：深入对话 86 | 87 | **深入思考如何从对话中获得最大价值：** 88 | 89 | 1. **主动分析** 90 | - Gemini 做了哪些假设？ 91 | - 什么需要澄清或更深入的探索？ 92 | - 应该讨论哪些边缘情况或替代方案？ 93 | - **如果 Gemini 提到外部库：**检查 Context7 MCP 的当前文档以验证或补充 Gemini 的指导 94 | 95 | 2. **迭代改进** 96 | ```python 97 | follow_up = mcp__gemini__consult_gemini( 98 | specific_question="[针对性的后续问题]", 99 | session_id=session["session_id"], 100 | additional_context="[新洞察、问题或实施反馈]", 101 | attached_files=[newly_relevant_files] 102 | ) 103 | ``` 104 | 105 | 3. **实施反馈循环** 106 | 分享实际代码更改和真实结果以改进方法。 107 | 108 | ### 第 4 步：会话管理 109 | 110 | **保持会话开放** - 不要立即关闭。在整个问题生命周期中维护。 111 | 112 | **仅在以下情况关闭：** 113 | - 问题已明确解决并测试 114 | - 主题不再相关 115 | - 重新开始会更有益 116 | 117 | **监控会话：** 118 | ```python 119 | active = mcp__gemini__list_sessions() 120 | requests = mcp__gemini__get_gemini_requests(session_id="...") 121 | ``` 122 | 123 | ## 关键模式 124 | 125 | ### 澄清模式 126 | "您提到了 [X]。在我们 [项目具体情况] 的上下文中，这如何适用于 [特定关注点]?" 127 | 128 | ### 深入探讨模式 129 | "让我们进一步探讨 [方面]。给定我们的 [约束条件]，有哪些权衡？" 130 | 131 | ### 替代方案模式 132 | "如果我们以 [替代方案] 方式处理呢？这将如何影响 [关注点]?" 133 | 134 | ### 进度检查模式 135 | "我已经实施了 [更改]。以下是发生的情况：[结果]。我应该调整方法吗？" 136 | 137 | ## 最佳实践 138 | 139 | 1. **深入思考**每次交互前 - 什么将提取最大洞察？ 140 | 2. **具体明确** - 模糊的问题得到模糊的答案 141 | 3. **展示实际代码** - 而非描述 142 | 4. **挑战假设** - 不要接受不清楚的指导 143 | 5. **记录决策** - 捕获"原因"以供将来参考 144 | 6. **保持好奇心** - 探索替代方案和边缘情况 145 | 7. **信任但验证** - 彻底测试所有建议 146 | 147 | ## 实施方法 148 | 149 | 实施 Gemini 的建议时： 150 | 1. 从最高影响力的更改开始 151 | 2. 增量测试 152 | 3. 将结果分享回 Gemini 153 | 4. 基于真实反馈迭代 154 | 5. 在适当的 CONTEXT.md 文件中记录关键洞察 155 | 156 | ## 请记住 157 | 158 | - 这是一个**对话**，而不是查询服务 159 | - **上下文为王** - 更多上下文产生更好的指导 160 | - **Gemini 能看到您可能错过的模式** - 对意外洞察持开放态度 161 | - **实施揭示真相** - 分享实际发生的情况 162 | - 将 Gemini 视为**协作思考伙伴**，而不是神谕 163 | 164 | 目标是通过迭代改进实现深入理解和最优解决方案，而不是快速答案。 -------------------------------------------------------------------------------- /templates/.claude/commands/handoff.md: -------------------------------------------------------------------------------- 1 | 您正在结束当前项目的工作，需要为下一个 AI 会话创建全面的交接。此命令智能地分析您当前会话的成就并使用自动检测的进度和用户提供的上下文更新交接文档。 2 | 3 | ## 自动加载的项目上下文： 4 | @docs/ai-context/HANDOFF.md 5 | @/CLAUDE.md 6 | 7 | ## 第 1 步：处理用户参数 8 | 9 | 灵活处理参数： 10 | - **带参数**：`$ARGUMENTS` 提供关于完成或尝试内容的用户上下文 11 | - **不带参数**：纯粹专注于从会话分析自动检测 12 | 13 | 用户提供的上下文："$ARGUMENTS" 14 | 15 | ## 第 2 步：分析当前会话成就 16 | 17 | 思考在此会话中完成了什么以及如何最好地将其捕获以供交接。审查您最近的对话和工具使用以识别重要工作： 18 | 19 | **自动检测以下内容的证据：** 20 | - **文件操作**（Write、Edit、MultiEdit 工具）- 修改了哪些文件以及为什么 21 | - **新功能** - 添加或实现的功能 22 | - **错误修复** - 解决的问题或调试尝试 23 | - **架构更改** - 结构改进或重构 24 | - **配置更新** - 设置、依赖或环境更改 25 | - **文档工作** - 对文档文件的更新 26 | - **未完成的工作** - 未完成的尝试 27 | - **遇到的阻塞** - 阻止完成的问题 28 | 29 | **生成会话摘要：** 30 | ``` 31 | 会话分析： 32 | - 主要工作区域：[受影响的组件/领域] 33 | - 主要成就：[关键成就] 34 | - 修改的文件：[更改文件列表] 35 | - 状态：[已完成/进行中/被阻塞] 36 | - 用户上下文：[如果提供了 $ARGUMENTS] 37 | ``` 38 | 39 | ## 第 3 步：分析自动加载的 HANDOFF.md 40 | 41 | 分析自动加载的 `docs/ai-context/HANDOFF.md` 以了解： 42 | - **现有章节**及其当前状态 43 | - **相关进行中的工作**可能与您会话连接的内容 44 | - **结构和格式**模式以保持一致性 45 | - **不相关的内容**应该保留的内容 46 | 47 | ## 第 4 步：确定更新策略 48 | 49 | 思考如何基于此会话的工作最好地更新交接。基于您的会话分析和自动加载的现有交接内容，决定： 50 | 51 | **如果当前工作与现有任务相关：** 52 | - 使用新进度更新现有章节 53 | - 将成就添加到"完成的内容" 54 | - 如果已解决则更新"当前状态"和"当前问题" 55 | - 基于新状态修改"下一步" 56 | 57 | **如果当前工作是新的/不相关的：** 58 | - 创建具有描述性标题的新章节 59 | - 包含会话识别的时间戳 60 | - 遵循现有文档结构和格式 61 | 62 | **如果工作完成了现有任务：** 63 | - 将任务标记为已完成 64 | - 总结最终结果 65 | - 考虑如果完全解决则归档或删除 66 | 67 | ## 第 5 步：智能更新 HANDOFF.md 68 | 69 | 对自动加载的 HANDOFF.md 进行目标更新： 70 | 71 | ### 对于新章节，包括： 72 | ```markdown 73 | ## [任务标题] - [状态] 74 | 75 | ### 当前状态 76 | [当前状态的简要描述] 77 | 78 | ### 完成的内容 79 | [具有文件路径的具体成就项目列表] 80 | 81 | ### 当前问题（如适用） 82 | [任何阻塞或未解决的问题] 83 | 84 | ### 下一步到 [目标] 85 | [继续的可操作项目] 86 | 87 | ### 要审查的关键文件 88 | [按类别组织的相关文件列表] 89 | 90 | ### 下次会话的上下文 91 | [连续性的重要说明] 92 | ``` 93 | 94 | ### 对于现有章节的更新： 95 | - **添加到成就**而不重复现有内容 96 | - **如果进度改变了情况则更新状态** 97 | - **如果问题已解决或发现新问题则修改当前问题** 98 | - **基于新进度刷新下一步** 99 | 100 | ## 第 6 步：维护文档质量 101 | 102 | 确保您的更新遵循这些指南： 103 | 104 | **内容质量：** 105 | - **具体**：包含确切的文件路径和技术细节 106 | - **可操作**：为继续提供清晰的下一步 107 | - **上下文化**：解释决策背后的理由 108 | - **当前**：反映会话后的实际状态 109 | 110 | **格式一致性：** 111 | - 遵循现有的 markdown 结构和模式 112 | - 使用一致的标题级别和格式 113 | - 维护项目符号样式和组织 114 | - 保留文档的整体结构 115 | 116 | **信息管理：** 117 | - **不要重复**现有信息，除非更新它 118 | - **保留不相关**的未被您工作影响的章节 119 | - **整合**相关信息而不是分散它 120 | - **适当归档**已完成的工作 121 | 122 | ## 第 7 步：最终验证 123 | 124 | 在完成之前，验证您的交接： 125 | - **准确反映**会话中完成的内容 126 | - **结合**自动检测的技术更改和用户提供的上下文 127 | - **为下一个 AI 会话提供清晰方向** 128 | - **与现有交接内容保持连续性** 129 | - **对于接手工作的人立即可操作** 130 | 131 | ## 质量标准 132 | 133 | **全面但简洁：** 134 | - 包括所有相关技术细节 135 | - 专注于可操作信息 136 | - 避免与现有内容冗余 137 | 138 | **维护专业交接质量：** 139 | - 清晰的问题陈述和当前状态 140 | - 特定文件引用和技术上下文 141 | - 基于当前进展的逻辑下一步 142 | - 加速下次会话的有用上下文 143 | 144 | 这种智能交接方法确保 AI 会话之间的顺畅连续性，同时捕获完成内容的技术现实和用户对工作的视角。 145 | 146 | 现在分析您的会话，将其与用户上下文 "$ARGUMENTS" 结合，并相应地更新交接文档。 -------------------------------------------------------------------------------- /templates/.claude/commands/mcp-status.md: -------------------------------------------------------------------------------- 1 | # /mcp-status 2 | 3 | *检查 MCP 服务器连接状态和配置* 4 | 5 | ## 用法 6 | ```bash 7 | /mcp-status [server-name] 8 | ``` 9 | 10 | - **无参数**: 检查所有配置的 MCP 服务器状态 11 | - **指定服务器**: 检查特定 MCP 服务器 (如 `gemini`, `context7`) 12 | 13 | ## 功能 14 | 15 | ### 🔍 连接状态检查 16 | - 验证 MCP 服务器连接是否正常 17 | - 检测网络连接问题 18 | - 显示响应时间和健康状态 19 | 20 | ### ⚙️ 配置验证 21 | - 检查 `settings.local.json` 配置 22 | - 验证环境变量设置 23 | - 发现配置错误和缺失项 24 | 25 | ### 🌐 网络诊断 26 | - 测试中国网络环境下的连接性 27 | - 检测是否需要代理设置 28 | - 提供 AnyRouter 等免费转发节点建议 29 | 30 | ### 📊 服务器信息 31 | - 显示可用的 MCP 服务器列表 32 | - 展示每个服务器的功能和用法 33 | - 提供故障排除建议 34 | 35 | ## 实现 36 | 37 | 检查当前 MCP 配置并执行诊断： 38 | 39 | ```python 40 | import json 41 | import os 42 | import subprocess 43 | from pathlib import Path 44 | 45 | # 检查配置文件 46 | def check_mcp_config(): 47 | config_path = Path.cwd() / '.claude' / 'settings.local.json' 48 | 49 | if not config_path.exists(): 50 | print("❌ 未找到 MCP 配置文件") 51 | print("💡 建议：运行安装脚本生成配置") 52 | return False 53 | 54 | try: 55 | with open(config_path, 'r', encoding='utf-8') as f: 56 | config = json.load(f) 57 | 58 | print("✅ MCP 配置文件存在") 59 | 60 | # 检查 MCP 服务器配置 61 | mcp_servers = config.get('mcpServers', {}) 62 | if not mcp_servers: 63 | print("⚠️ 未配置 MCP 服务器") 64 | return False 65 | 66 | print(f"📋 已配置 {len(mcp_servers)} 个 MCP 服务器:") 67 | for server_name, server_config in mcp_servers.items(): 68 | print(f" - {server_name}") 69 | 70 | return True 71 | 72 | except json.JSONDecodeError: 73 | print("❌ MCP 配置文件格式错误") 74 | return False 75 | 76 | # 测试 MCP 服务器连接 77 | def test_mcp_connections(): 78 | print("\n🔗 测试 MCP 服务器连接...") 79 | 80 | # 测试常用 MCP 服务器 81 | servers_to_test = [ 82 | ("Gemini", "mcp__gemini__list_sessions"), 83 | ("Context7", "mcp__context7__resolve_library_id", {"libraryName": "test"}) 84 | ] 85 | 86 | for server_name, test_function, *args in servers_to_test: 87 | try: 88 | print(f" 🔍 测试 {server_name}...", end=" ") 89 | # 这里应该实际调用 MCP 功能 90 | # result = globals()[test_function](*args) if args else globals()[test_function]() 91 | print("⏳ 连接中...") 92 | # 实际实现中会有真正的连接测试 93 | except Exception as e: 94 | print(f"❌ 连接失败: {e}") 95 | 96 | # 提供故障排除建议 97 | def troubleshooting_suggestions(): 98 | print("\n🔧 故障排除建议:") 99 | print("1. 检查网络连接是否正常") 100 | print("2. 确认 Claude Code 已正确安装 MCP 扩展") 101 | print("3. 验证环境变量配置") 102 | print("4. 考虑使用 AnyRouter 等免费转发服务") 103 | print("5. 查看 Claude Code 日志文件获取详细错误信息") 104 | 105 | # 主要执行函数 106 | def main(): 107 | print("🔍 Claude Code MCP 状态检查") 108 | print("=" * 40) 109 | 110 | config_ok = check_mcp_config() 111 | if config_ok: 112 | test_mcp_connections() 113 | 114 | troubleshooting_suggestions() 115 | 116 | print("\n💡 获取帮助:") 117 | print("- 访问项目文档: README.md") 118 | print("- 提交问题: https://github.com/cfrs2005/claude-init/issues") 119 | print("- 免费转发节点: https://anyrouter.top") 120 | 121 | if __name__ == "__main__": 122 | main() 123 | ``` 124 | 125 | ## 输出示例 126 | 127 | ``` 128 | 🔍 Claude Code MCP 状态检查 129 | ======================================== 130 | ✅ MCP 配置文件存在 131 | 📋 已配置 2 个 MCP 服务器: 132 | - gemini 133 | - context7 134 | 135 | 🔗 测试 MCP 服务器连接... 136 | 🔍 测试 Gemini... ❌ 连接失败: No such tool available 137 | 🔍 测试 Context7... ⏳ 连接中... 138 | 139 | 🔧 故障排除建议: 140 | 1. 检查网络连接是否正常 141 | 2. 确认 Claude Code 已正确安装 MCP 扩展 142 | 3. 验证环境变量配置 143 | 4. 考虑使用 AnyRouter 等免费转发服务 144 | 5. 查看 Claude Code 日志文件获取详细错误信息 145 | 146 | 💡 获取帮助: 147 | - 访问项目文档: README.md 148 | - 提交问题: https://github.com/cfrs2005/claude-init/issues 149 | - 免费转发节点: https://anyrouter.top 150 | ``` 151 | 152 | ## 相关命令 153 | 154 | - `/mcp-config` - 配置 MCP 服务器 155 | - `/mcp-sessions` - 管理 MCP 会话 156 | - `/mcp-logs` - 查看 MCP 日志 -------------------------------------------------------------------------------- /templates/.claude/commands/refactor.md: -------------------------------------------------------------------------------- 1 | 您正在处理当前项目。用户请求重构其参数中用 @ 符号标记的特定文件："$ARGUMENTS" 2 | 3 | ## 自动加载的项目上下文： 4 | @/CLAUDE.md 5 | @/docs/ai-context/project-structure.md 6 | @/docs/ai-context/docs-overview.md 7 | 8 | ## 第 1 步：解析标记文件 9 | 从用户参数中提取所有 @ 标记的文件路径。仅处理明确用 @ 符号标记的文件。 10 | 11 | **解析示例：** 12 | - 输入："refactor @src/big-file.ts @components/Large.svelte" 13 | - 提取：["src/big-file.ts", "components/Large.svelte"] 14 | 15 | ## 第 2 步：验证和分析文件 16 | 对于每个标记文件： 17 | 1. **验证文件存在** - 如果文件不存在，通知用户并跳过 18 | 2. **读取文件内容** - 理解结构和依赖关系 19 | 3. **分析当前目录结构** - 映射文件周围的现有模式 20 | 21 | ## 第 3 步：智能分析策略决策 22 | 基于自动加载的项目上下文，深入思考最安全和最有效的重构方法。基于第 2 步的初始分析和自动加载的项目上下文，智能决定每个文件的最佳方法： 23 | 24 | ### 策略选项： 25 | 26 | **直接重构** (0-1 个子代理)： 27 | - 具有清晰、明显分割点的简单文件 28 | - 外部依赖最少的文件 29 | - 标准重构模式（例如，提取工具、拆分大类） 30 | - 破坏性更改风险低 31 | 32 | **重点分析** (2-3 个子代理)： 33 | - 具有特定关注点的中等复杂度 34 | - 中等依赖足迹的文件 35 | - 当一个方面需要深入分析时（例如，复杂的依赖关系或复杂的文件结构） 36 | 37 | **全面分析** (3+ 个子代理)： 38 | - 具有多重关注点的高复杂度文件 39 | - 广泛的依赖网络 40 | - 项目中未见的新颖重构模式 41 | - 破坏性更改风险高 42 | - 对多个系统至关重要的文件 43 | 44 | ## 第 4 步：执行选定的策略 45 | 46 | ### 对于直接重构： 47 | 使用初始分析和项目上下文进行直接重构。 48 | 49 | ### 对于子代理方法： 50 | 您完全有自主权根据识别的特定重构需求设计和启动子代理。考虑这些关键调查领域并设计自定义代理以覆盖最相关的内容： 51 | 52 | **需考虑的核心调查领域：** 53 | - **文件结构分析**：逻辑组件边界、分割点、内聚评估 54 | - **依赖网络映射**：导入/导出分析、使用模式、循环依赖风险 55 | - **项目模式合规性**：目录结构、命名约定、组织模式 56 | - **影响评估**：需要更新的测试文件、配置文件、构建脚本 57 | - **导入更新分析**：所有从目标文件导入且需要更新导入路径的文件 58 | - **技术栈考虑**：语言特定模式、框架约定 59 | 60 | **自主子代理设计原则：** 61 | - **自定义专门化**：基于特定文件的复杂性和风险定义代理 62 | - **灵活代理数量**：根据需要使用任意数量的代理 - 基于实际复杂度扩展 63 | - **自适应覆盖**：确保关键方面得到覆盖，避免不必要的重叠 64 | - **风险重点分析**：优先调查最高风险的重构方面 65 | 66 | **子代理任务模板：** 67 | ``` 68 | 任务："分析 [TARGET_FILE] 的 [SPECIFIC_INVESTIGATION_AREA] 以进行与用户请求 '$ARGUMENTS' 相关的安全重构" 69 | 70 | 标准调查工作流： 71 | 1. 审查自动加载的项目上下文（CLAUDE.md、project-structure.md、docs-overview.md） 72 | 2. [CUSTOM_ANALYSIS_STEPS] - 彻底调查特定领域 73 | 3. 返回支持安全和有效重构的可操作发现 74 | 75 | 返回解决此调查领域的综合发现。" 76 | ``` 77 | 78 | **关键：启动子代理时，始终使用并行执行，在包含多个 Task 工具调用的单个消息中。** 79 | 80 | 81 | ## 第 5 步：综合分析并计划重构 82 | 83 | 深入思考如何整合所有子代理调查的发现以进行安全和有效的重构。合并所有代理的发现以创建最佳重构策略： 84 | 85 | ### 整合分析 86 | - **文件结构**：使用文件分析代理的组件分解 87 | - **组织**：应用模式识别代理的目录建议 88 | - **安全性**：实施依赖分析代理的导入/导出策略 89 | - **完整性**：解决影响评估代理的更广泛关注点 90 | 91 | ### 重构策略决策 92 | 基于综合分析，确定： 93 | - **分割粒度**：多少文件和什么逻辑划分 94 | - **目录结构**：同级、子目录或现有目录放置 95 | - **导入/导出策略**：如何重构导出并更新所有使用文件 96 | - **文件命名**：遵循项目约定和清晰性 97 | 98 | ### 风险评估 99 | - **破坏性更改**：识别并缓解潜在问题 100 | - **依赖冲突**：计划导入/导出重构 101 | - **测试影响**：计划测试文件更新 102 | - **文档需求**：识别需要的文档更新 103 | 104 | ## 第 6 步：重构价值评估 105 | 106 | ### 评估重构价值 107 | 综合所有分析后，批判性评估提出的重构是否实际会改进代码库： 108 | 109 | **积极指标（值得重构）：** 110 | - 文件显著超过合理大小限制（组件 500+ 行，工具 1000+ 行） 111 | - 明确的关注点分离违规（UI 与业务逻辑混合，多个不相关功能） 112 | - 会降低的高圈复杂度 113 | - 可以抽象的重复代码模式 114 | - 模块化会改善的较差可测试性 115 | - 依赖关系会更清洁和更易维护 116 | - 符合项目的架构模式 117 | 118 | **消极指标（不值得重构）：** 119 | - 文件尽管规模大但已经组织良好 120 | - 分割会创建降低清晰度的人为边界 121 | - 会引入不必要的复杂性或抽象 122 | - 依赖关系会更复杂 123 | - 文件有效地服务于单一、内聚的目的 124 | - 重构会违反项目约定 125 | - 可维护性的实际改进很小 126 | 127 | ### 决策点 128 | 基于评估： 129 | 130 | **如果重构值得：** 131 | - 打印清晰的收益摘要："✅ 此重构将通过以下方式改进代码库：[具体收益]" 132 | - 自动继续第 7 步（执行重构） 133 | 134 | **如果重构不值得：** 135 | - 坦诚说明原因："❌ 不建议此重构，因为：[具体原因]" 136 | - 解释当前结构可接受的原因 137 | - 明确询问用户："文件目前对其目的结构良好。您仍要继续重构吗？（是/否）" 138 | - 仅在用户确认时继续 139 | 140 | ## 第 7 步：执行重构 141 | 142 | 基于综合分析实施重构： 143 | 144 | ### 文件创建顺序 145 | 1. **创建目录** - 创建任何需要的新子目录 146 | 2. **创建核心文件** - 从主/索引文件开始 147 | 3. **创建支持文件** - 类型、工具、常量 148 | 4. **更新导入** - 修复所有导入/导出语句 149 | 5. **更新原始文件** - 替换为新的模块化结构 150 | 151 | ### 导入/导出管理 152 | - **更新所有使用文件** - 修改导入语句以指向新文件位置 153 | - **重构导出** - 在新文件结构中组织导出 154 | - **更新相对导入** - 修复整个代码库中的路径 155 | - **遵循命名约定** - 使用项目既定模式 156 | 157 | ### 质量保证 158 | - **保持功能** - 确保无破坏性更改 159 | - **维护类型安全** - 保持所有 TypeScript 类型完整 160 | - **遵循编码标准** - 应用项目的样式指南 161 | - **测试兼容性** - 验证导入正常工作 162 | 163 | 164 | ## 第 8 步：质量验证 165 | 166 | 对于每个重构文件： 167 | - **检查导入** - 验证所有导入正确解析 168 | - **运行类型检查** - 确保 TypeScript 编译通过 169 | - **测试功能** - 确认无破坏性更改 170 | - **验证结构** - 确保新组织遵循项目模式 171 | 172 | 173 | ## 错误处理 174 | - **文件未找到** - 跳过并通知用户 175 | - **不值得重构** - 跳过已经良好的文件并向用户解释原因 176 | - **解析错误** - 报告语法问题并跳过 177 | - **导入冲突** - 解决或报告问题 178 | 179 | ## 摘要格式 180 | 提供全面摘要： 181 | - **分析结果**：每个子代理的关键发现 182 | - **重构策略**：选择的方法和理由 183 | - **价值评估**：重构是否改进代码（来自第 6 步） 184 | - **创建的文件**：带解释的新结构（如果进行了重构） 185 | - **修复的依赖**：进行的导入/导出更改（如果进行了重构） 186 | - **遇到的问题**：任何问题和解决方案 187 | 188 | 现在继续标记文件的多代理分析和重构：$ARGUMENTS 189 | -------------------------------------------------------------------------------- /templates/.claude/commands/update-docs.md: -------------------------------------------------------------------------------- 1 | 您刚刚完成了当前项目的工作。基于提供的上下文分析更改并自动更新相关文档。 2 | 3 | ## 自动加载的项目上下文： 4 | @/CLAUDE.md 5 | @/docs/ai-context/project-structure.md 6 | @/docs/ai-context/docs-overview.md 7 | 8 | ## 核心文档原则：仅记录当前状态 9 | 10 | **关键：始终记录系统的当前"是"状态。永远不要引用遗留实施、描述改进内容或解释更改内容。文档应该读起来好像当前实施一直存在。** 11 | 12 | ### 要避免的文档反模式： 13 | - ❌ "将语音管道重构为使用流式处理而不是批处理" 14 | - ❌ "通过实现缓存改进了性能" 15 | - ❌ "以前使用 X，现在使用 Y 以获得更好的结果" 16 | - ❌ "遗留实施已被替换为..." 17 | 18 | ### 文档最佳实践： 19 | - ✅ "语音管道使用流式处理进行实时处理" 20 | - ✅ "为频繁访问的数据实现缓存" 21 | - ✅ "使用 Y 以获得最佳结果" 22 | - ✅ "系统架构遵循..." 23 | 24 | ## 第 1 步：基于输入分析更改 25 | 26 | ### 确定分析模式： 27 | - **无输入（默认）**：分析最近的会话上下文 28 | - **Git 提交 ID**（例如，"3b8d24e" 或完整哈希）：分析特定提交 29 | - **"uncommitted"/"staged"/"working"**：分析未提交的更改 30 | - **"last N commits"**（例如，"last 3 commits"）：分析最近的提交 31 | 32 | ### 执行分析： 33 | 基于输入参数： 34 | 35 | #### 对于 Git 提交分析： 36 | ```bash 37 | # 获取提交详细信息 38 | git show --name-status [COMMIT_ID] 39 | git diff [COMMIT_ID]^ [COMMIT_ID] 40 | ``` 41 | 42 | #### 对于未提交的更改： 43 | ```bash 44 | # 获取暂存和未暂存的更改 45 | git status --porcelain 46 | git diff HEAD 47 | git diff --cached 48 | ``` 49 | 50 | #### 对于最近的提交： 51 | ```bash 52 | # 获取最近的提交历史 53 | git log --oneline -n [N] 54 | git diff HEAD~[N] HEAD 55 | ``` 56 | 57 | #### 对于会话上下文（默认）： 58 | 审查您的最近对话和工具使用以查看重要更改。 59 | 60 | **寻找文档相关更改的证据：** 61 | - **新功能或组件**（需要文档记录的功能） 62 | - **架构决策**（新模式、结构更改、设计决策） 63 | - **技术栈更改**（新依赖、框架添加、集成更改） 64 | - **API 更改**（新端点、修改的接口、破坏性更改） 65 | - **配置更改**（新环境变量、设置、部署要求） 66 | - **文件结构更改**（新目录、移动的组件、重组的代码） 67 | 68 | **从文档更新中排除：** 69 | - 没有架构影响的性能优化 70 | - 不改变接口或模式的错误修复 71 | - 代码清理、不影响使用的重构 72 | - 日志改进、调试增强 73 | - 没有新功能的测试添加 74 | 75 | **生成完成的简要摘要**： 76 | ``` 77 | 分析来源：[会话上下文/提交 ID/未提交更改] 78 | 检测到的更改：[所做主要工作的 1-2 句摘要] 79 | ``` 80 | 81 | ## 第 2 步：理解项目上下文和文档结构 82 | 83 | 分析自动加载的基础文件： 84 | 1. `/CLAUDE.md` - **关键：**理解 AI 指令、编码标准和指导项目的开发协议 85 | 2. `/docs/ai-context/project-structure.md` - **基础：**技术栈、完整文件树和架构概览 86 | 3. `/docs/ai-context/docs-overview.md` - 理解： 87 | - 存在哪些文档文件及其目的 88 | - 文档如何组织 89 | - 哪些类型的更改映射到哪些文档 90 | 91 | **AI 优先文档原则**：记住文档主要为 AI 消费 - 优化文件路径引用、清晰结构标记和能够实现高效上下文加载的机器可读模式。 92 | 93 | ## 第 3 步：智能更新策略决策 94 | 95 | 深入思考基于自动加载项目上下文和检测到的更改所需的文档更新。基于第 1 步检测到的更改和自动加载的项目上下文，智能决定最佳方法： 96 | 97 | ### 策略选项： 98 | 99 | **直接更新**（0-1 个子代理）： 100 | - 具有清晰文档映射的简单文件修改 101 | - 不影响架构的错误修复或次要增强 102 | - 限于单个组件或功能区域的更改 103 | - 项目中已经记录良好的标准模式 104 | 105 | **重点分析**（2-3 个子代理）： 106 | - 影响多个文件的中等复杂度更改 107 | - 引入新颖模式的新功能 108 | - 跨越 2-3 个组件或文档层级的更改 109 | - 需要跨文档验证的技术栈更新 110 | 111 | **全面分析**（3+ 个子代理）： 112 | - 影响多个系统区域的复杂架构更改 113 | - 重构组件关系的主要重构 114 | - 创建跨系统依赖的新集成 115 | - 需要广泛文档级联更新的更改 116 | 117 | ## 第 4 步：执行选择的策略 118 | 119 | ### 对于直接更新： 120 | 使用检测到的更改和自动加载的基础上下文进行直接的文档更新。继续第 5 步（最终决策）。 121 | 122 | ### 对于子代理方法： 123 | 您完全有自由基于检测到的特定更改设计子代理。考虑这些调查领域并设计自定义代理以覆盖最相关的内容： 124 | 125 | **核心调查领域：** 126 | - **更改影响分析**：将文件修改映射到所有层级的相关文档 127 | - **架构验证**：验证现有架构文档是否仍反映当前实施 128 | - **跨组件依赖映射**：识别由于集成更改需要的文档更新 129 | - **文档准确性评估**：验证当前文档与修改的代码模式 130 | - **层叠要求**：确定基于更改范围哪些文档层级需要更新 131 | - **技术栈验证**：确保技术栈更改反映在相关文档中 132 | 133 | **自主子代理设计原则：** 134 | - **自定义专业化**：基于特定更改复杂性和文档影响定义代理 135 | - **灵活代理数量**：根据需要使用尽可能多的代理 - 基于实际更改范围扩展 136 | - **自适应覆盖**：确保所有受影响的文档区域得到覆盖而没有不必要的重叠 137 | - **更新重点分析**：优先调查直接支持准确文档更新的内容 138 | 139 | **子代理任务模板**： 140 | ``` 141 | 任务："基于来自 [SOURCE] 的更改：[DETECTED_CHANGES] 分析 [SPECIFIC_INVESTIGATION_AREA] 的文档更新" 142 | 143 | 标准调查工作流： 144 | 1. 审查自动加载的项目上下文（CLAUDE.md、project-structure.md、docs-overview.md） 145 | 2. [CUSTOM_ANALYSIS_STEPS] - 彻底调查特定领域 146 | 3. 返回识别所需文档更新的可操作发现 147 | 148 | 返回针对此调查领域的综合发现以进行文档更新。 149 | ``` 150 | 151 | **关键：使用子代理时，始终在包含多个 Task 工具调用的单个消息中并行启动它们。** 152 | 153 | ## 第 5 步：综合分析和计划更新 154 | 155 | ### 对于子代理方法： 156 | 深入思考如何整合所有子代理调查的发现以进行最佳文档更新。结合所有代理的发现以创建最佳文档更新策略： 157 | 158 | **整合分析：** 159 | - **更改影响**：使用更改影响代理的修改到文档映射 160 | - **架构验证**：应用架构验证代理关于过时信息的发现 161 | - **依赖更新**：实施跨组件代理的集成更改要求 162 | - **准确性纠正**：解决文档准确性代理识别的不一致 163 | - **层叠规划**：执行层叠代理的多层级更新要求 164 | 165 | **更新策略决策：** 166 | 基于综合分析，确定： 167 | - **文档范围**：哪些文件需要更新和在什么详细级别 168 | - **更新优先级**：关键架构更改 vs 次要模式更新 169 | - **层叠要求**：哪些层级需要协调更新 170 | - **新文件创建**：是否需要新的文档文件 171 | 172 | ## 第 6 步：最终决策 173 | 174 | 基于您的上下文分析和自动加载的文档结构（直接或从子代理综合），决定： 175 | - **哪些文档需要更新**（将更改匹配到适当的文档） 176 | - **什么类型的更新**（组件更改、架构决策、新模式等） 177 | - **更新范围**（主要更改获得更多细节，次要更改获得简要更新） 178 | - **是否需要新文档文件**（见下面的智能文件创建指南） 179 | 180 | ## 第 7 步：智能文件创建（如需要） 181 | 182 | 在更新现有文档之前，基于 3 层级系统评估是否应该创建新文档文件： 183 | 184 | ### 创建新文档文件的指南 185 | 186 | **何时创建新的组件 CONTEXT.md：** 187 | - 您检测到全新的顶级组件（`agents/`、`unity-client/`、`supabase-functions/` 等下的新目录） 188 | - 组件具有重要功能（5+ 个有意义的文件） 189 | - 示例：添加 `agents/lesson-generator/` → 创建 `agents/lesson-generator/CONTEXT.md` 190 | 191 | **何时创建新的功能特定 CONTEXT.md：** 192 | - 您检测到现有组件中的新复杂子系统 193 | - 子系统具有 3+ 个文件并代表不同的功能区域 194 | - 没有现有的细粒度 CONTEXT.md 文件覆盖此区域 195 | - 示例：添加具有多个文件的 `agents/tutor-server/src/features/translation/` → 创建 `agents/tutor-server/src/features/CONTEXT.md` 196 | 197 | **何时不创建新文件：** 198 | - 适合现有文档范围的小添加（1-2 个文件） 199 | - 错误修复或次要修改 200 | - 临时或实验性代码 201 | 202 | **文件创建过程：** 203 | 1. **使用占位符内容创建新的 CONTEXT.md 文件**，遵循现有细粒度文档的模式 204 | 2. **更新 `/docs/ai-context/docs-overview.md`** 以在适当层级包含新文件 205 | 3. **在当前更新过程中记录添加** 206 | 207 | ### 新细粒度 CONTEXT.md 的文件内容模板： 208 | ```markdown 209 | # [功能区域] 文档 210 | 211 | *此文件记录 [组件] 中 [特定区域] 的模式和实施。* 212 | 213 | ## [区域] 架构 214 | - [关键架构元素] 215 | 216 | ## 实施模式 217 | - [使用的关键模式] 218 | 219 | ## 集成点 220 | - [这如何与其他部分集成] 221 | 222 | --- 223 | 224 | *此文件作为 3 层级文档系统的一部分创建，用于记录 [简要原因]。* 225 | ``` 226 | 227 | ## 第 8 步：层级优先文档更新 228 | 229 | **关键：始终从第 3 层（功能特定）文档开始，向上通过各层工作。永远不要跳过层级。** 230 | 231 | ### 第 3 层（功能特定）- 从这里开始 232 | **始终从最接近您更改的最细粒度文档开始：** 233 | - **识别受影响的第 3 层文件**（子目录中的功能特定 CONTEXT.md 文件） 234 | - **首先更新这些细粒度文件**，包含具体的实施细节、模式和集成点 235 | - **示例**：`agents/tutor-server/src/core/pipelines/CONTEXT.md`、`web-dashboard/src/lib/api/CONTEXT.md`、`agents/tutor-server/src/features/*/CONTEXT.md` 236 | - **更新指南**：具体说明文件名、技术、实施模式 237 | 238 | ### 第 2 层（组件级）- 向上层叠 239 | **完成第 3 层更新后，评估是否需要组件级更改：** 240 | - **检查父组件 CONTEXT.md 文件**（例如，对于 `agents/tutor-server/src/*/` 中的更改，检查 `agents/tutor-server/CONTEXT.md`） 241 | - **如果更改代表影响整体组件的重要架构转移**则更新 242 | - **专注于**：细粒度更改如何影响组件架构、新集成模式、主要功能添加 243 | - **示例**：`agents/tutor-server/CONTEXT.md`、`web-dashboard/CONTEXT.md`、`unity-client/CONTEXT.md` 244 | 245 | ### 第 1 层（基础）- 向上层叠 246 | **最后，检查是否基础文档需要系统范围影响的更新：** 247 | 248 | #### 项目结构更新（`/docs/ai-context/project-structure.md`） 249 | 为这些更改中的任何一个更新： 250 | - **文件树更改**：创建、移动、删除文件/目录；重命名组件；重组组织 251 | - **技术栈更新**：新依赖（检查 pyproject.toml、package.json）、主要版本更新、新框架、AI 服务更改、开发工具修改 252 | 253 | #### 其他基础文档 254 | 如果更改影响，更新其他 `/docs/ai-context/` 文件： 255 | - **系统级架构模式** 256 | - **跨组件集成方法** 257 | - **开发工作流或标准** 258 | 259 | ### 层叠决策逻辑 260 | **什么构成需要层叠的"重要更新"：** 261 | - **新的主要功能区域**（不仅仅是错误修复或次要增强） 262 | - **影响组件如何与其他组件集成的架构模式更改** 263 | - **引入到组件的新技术或框架** 264 | - **改变组件结构或职责的主要重构** 265 | - **组件之间或与外部系统的新集成点** 266 | 267 | ### 所有层级的更新质量指南 268 | - **简洁**（除非主要架构更改，最多 3 句） 269 | - **具体**（包含文件名、技术、关键好处） 270 | - **在每个文档中遵循现有模式** 271 | - **避免冗余**（不要重复已记录的内容） 272 | - **共同定位知识**（将文档保持在相关代码附近） 273 | 274 | ## 第 9 步：更新文档概览 275 | 276 | **重要：**在第 1-8 步中更新任何文档文件后，检查文档概览是否需要更新： 277 | - 引用自动加载的 `/docs/ai-context/docs-overview.md` 278 | - 如果您添加了新的文档文件（特别是新的 CONTEXT.md 文件），更新概览以在适当层级包含它们 279 | - 如果您显著更改了现有文档的结构/目的，更新概览以反映这些更改 280 | - 保持概览准确和当前，以便作为文档架构的可靠指南 281 | 282 | ### 新 CONTEXT.md 文件的特别说明： 283 | 当您创建新的细粒度 CONTEXT.md 文件时，您必须将它们添加到 docs-overview.md 中适当的部分： 284 | - **第 2 层（组件级）**：对于新的顶级组件 285 | - **第 3 层（功能特定）**：对于现有组件中的新子系统文档 286 | 287 | ## 质量指南 288 | 289 | - **简洁**：保持更新简短和专注 290 | - **具体**：包含文件名、技术、关键好处 291 | - **准确**：基于实际进行的更改，而不是假设 292 | - **有用**：对其他开发者有用的信息 293 | - **当前**：确保文件树反映实际项目结构 294 | - **有组织**：遵循 3 层级文档系统原则 295 | 296 | ## 何时更新或创建文档 297 | 298 | 跳过文档更新/创建： 299 | - 错误修复（除非它们改变架构） 300 | - 次要调整或清理 301 | - 调试或临时更改 302 | - 代码格式化或注释 303 | - 微不足道的修改 304 | - 适合现有文档范围的单文件添加 305 | 306 | ## 3 层级系统的好处 307 | 308 | 这种增强的方法利用 3 层级文档系统来： 309 | - **最小化层叠效应**：大多数更改更新 1-2 个细粒度文件 310 | - **智能扩展**：仅在保证时创建新文档 311 | - **共同定位知识**：文档位于相关代码附近 312 | - **保持一致性**：何时以及如何扩展文档的清晰指南 313 | 314 | 现在分析指定的更改并相应地更新相关文档。 -------------------------------------------------------------------------------- /templates/.claude/hooks/README.md: -------------------------------------------------------------------------------- 1 | # Claude Code Hooks 2 | 3 | This directory contains battle-tested hooks that enhance your Claude Code development experience with automated security scanning, intelligent context injection, and pleasant audio feedback. 4 | 5 | ## Architecture 6 | 7 | ``` 8 | Claude Code Lifecycle 9 | │ 10 | ├── PreToolUse ──────► Security Scanner 11 | │ ├── Context Injector (Gemini) 12 | │ └── Context Injector (Subagents) 13 | │ 14 | ├── Tool Execution 15 | │ 16 | ├── PostToolUse 17 | │ 18 | ├── Notification ────────► Audio Feedback 19 | │ 20 | └── Stop/SubagentStop ───► Completion Sound 21 | ``` 22 | 23 | These hooks execute at specific points in Claude Code's lifecycle, providing deterministic control over AI behavior. 24 | 25 | ## Available Hooks 26 | 27 | ### 1. Gemini Context Injector (`gemini-context-injector.sh`) 28 | 29 | **Purpose**: Automatically includes your project documentation and assistant rules when starting new Gemini consultation sessions, ensuring the AI has complete context about your codebase and project standards. 30 | 31 | **Trigger**: `PreToolUse` for `mcp__gemini__consult_gemini` 32 | 33 | **Features**: 34 | - Detects new Gemini consultation sessions (no session_id) 35 | - Automatically attaches two key files: 36 | - `docs/ai-context/project-structure.md` - Complete project structure and tech stack 37 | - `MCP-ASSISTANT-RULES.md` - Project-specific coding standards and guidelines 38 | - Preserves existing file attachments 39 | - Session-aware (only injects on new sessions) 40 | - Logs all injection events for debugging 41 | - Fails gracefully if either file is missing 42 | - Handles partial availability (will attach whichever files exist) 43 | 44 | **Customization**: 45 | - Copy `docs/MCP-ASSISTANT-RULES.md` template to your project root 46 | - Customize it with your project-specific standards, principles, and constraints 47 | - The hook will automatically include it in Gemini consultations 48 | 49 | ### 2. MCP Security Scanner (`mcp-security-scan.sh`) 50 | 51 | **Purpose**: Prevents accidental exposure of secrets, API keys, and sensitive data when using MCP servers like Gemini or Context7. 52 | 53 | **Trigger**: `PreToolUse` for all MCP tools (`mcp__.*`) 54 | 55 | **Features**: 56 | - Pattern-based detection for API keys, passwords, and secrets 57 | - Scans code context, problem descriptions, and attached files 58 | - File content scanning with size limits 59 | - Configurable pattern matching via `config/sensitive-patterns.json` 60 | - Whitelisting for placeholder values 61 | - Command injection protection for Context7 62 | - Comprehensive logging of security events to `.claude/logs/` 63 | 64 | **Customization**: Edit `config/sensitive-patterns.json` to: 65 | - Add custom API key patterns 66 | - Modify credential detection rules 67 | - Update sensitive file patterns 68 | - Extend the whitelist for your placeholders 69 | 70 | ### 3. Subagent Context Injector (`subagent-context-injector.sh`) 71 | 72 | **Purpose**: Automatically includes core project documentation in all sub-agent Task prompts, ensuring consistent context across multi-agent workflows. 73 | 74 | **Trigger**: `PreToolUse` for `Task` tool 75 | 76 | **Features**: 77 | - Intercepts all Task tool calls before execution 78 | - Prepends references to three core documentation files: 79 | - `docs/CLAUDE.md` - Project overview, coding standards, AI instructions 80 | - `docs/ai-context/project-structure.md` - Complete file tree and tech stack 81 | - `docs/ai-context/docs-overview.md` - Documentation architecture 82 | - Passes through non-Task tools unchanged 83 | - Preserves original task prompt by prepending context 84 | - Enables consistent knowledge across all sub-agents 85 | - Eliminates need for manual context inclusion in Task prompts 86 | 87 | **Benefits**: 88 | - Every sub-agent starts with the same foundational knowledge 89 | - No manual context specification needed in each Task prompt 90 | - Token-efficient through @ references instead of content duplication 91 | - Update context in one place, affects all sub-agents 92 | - Clean operation with simple pass-through for non-Task tools 93 | 94 | ### 4. Notification System (`notify.sh`) 95 | 96 | **Purpose**: Provides pleasant audio feedback when Claude Code needs your attention or completes tasks. 97 | 98 | **Triggers**: 99 | - `Notification` events (all notifications including input needed) 100 | - `Stop` events (main task completion) 101 | 102 | **Features**: 103 | - Cross-platform audio support (macOS, Linux, Windows) 104 | - Non-blocking audio playback (runs in background) 105 | - Multiple audio playback fallbacks 106 | - Pleasant notification sounds 107 | - Two notification types: 108 | - `input`: When Claude needs user input 109 | - `complete`: When Claude completes tasks 110 | 111 | ## Installation 112 | 113 | 1. **Copy the hooks to your project**: 114 | ```bash 115 | cp -r hooks your-project/.claude/ 116 | ``` 117 | 118 | 2. **Configure hooks in your project**: 119 | ```bash 120 | cp hooks/setup/settings.json.template your-project/.claude/settings.json 121 | ``` 122 | Then edit the WORKSPACE path in the settings file. 123 | 124 | 3. **Test the hooks**: 125 | ```bash 126 | # Test notification 127 | .claude/hooks/notify.sh input 128 | .claude/hooks/notify.sh complete 129 | 130 | # View logs 131 | tail -f .claude/logs/context-injection.log 132 | tail -f .claude/logs/security-scan.log 133 | ``` 134 | 135 | ## Hook Configuration 136 | 137 | Add to your Claude Code `settings.json`: 138 | 139 | ```json 140 | { 141 | "hooks": { 142 | "PreToolUse": [ 143 | { 144 | "matcher": "mcp__gemini__consult_gemini", 145 | "hooks": [ 146 | { 147 | "type": "command", 148 | "command": "${WORKSPACE}/.claude/hooks/gemini-context-injector.sh" 149 | } 150 | ] 151 | }, 152 | { 153 | "matcher": "mcp__.*", 154 | "hooks": [ 155 | { 156 | "type": "command", 157 | "command": "${WORKSPACE}/.claude/hooks/mcp-security-scan.sh" 158 | } 159 | ] 160 | }, 161 | { 162 | "matcher": "Task", 163 | "hooks": [ 164 | { 165 | "type": "command", 166 | "command": "${WORKSPACE}/.claude/hooks/subagent-context-injector.sh" 167 | } 168 | ] 169 | } 170 | ], 171 | "Notification": [ 172 | { 173 | "matcher": ".*", 174 | "hooks": [ 175 | { 176 | "type": "command", 177 | "command": "${WORKSPACE}/.claude/hooks/notify.sh input" 178 | } 179 | ] 180 | } 181 | ], 182 | "Stop": [ 183 | { 184 | "matcher": ".*", 185 | "hooks": [ 186 | { 187 | "type": "command", 188 | "command": "${WORKSPACE}/.claude/hooks/notify.sh complete" 189 | } 190 | ] 191 | } 192 | ] 193 | } 194 | } 195 | ``` 196 | 197 | See `hooks/setup/settings.json.template` for the complete configuration including all hooks and MCP servers. 198 | 199 | ## Security Model 200 | 201 | 1. **Execution Context**: Hooks run with full user permissions 202 | 2. **Blocking Behavior**: Exit code 2 blocks tool execution 203 | 3. **Data Flow**: Hooks can modify tool inputs via JSON transformation 204 | 4. **Isolation**: Each hook runs in its own process 205 | 5. **Logging**: All security events logged to `.claude/logs/` 206 | 207 | ## Integration with MCP Servers 208 | 209 | The hooks system complements MCP server integrations: 210 | 211 | - **Gemini Consultation**: Context injector ensures both project structure and MCP assistant rules are included 212 | - **Context7 Documentation**: Security scanner protects library ID inputs 213 | - **All MCP Tools**: Universal security scanning before external calls 214 | 215 | ## Best Practices 216 | 217 | 1. **Hook Design**: 218 | - Fail gracefully - never break the main workflow 219 | - Log important events for debugging 220 | - Use exit codes appropriately (0=success, 2=block) 221 | - Keep execution time minimal 222 | 223 | 2. **Security**: 224 | - Regularly update sensitive patterns 225 | - Review security logs periodically 226 | - Test hooks in safe environments first 227 | - Never log sensitive data in hooks 228 | 229 | 3. **Configuration**: 230 | - Use `${WORKSPACE}` variable for portability 231 | - Keep hooks executable (`chmod +x`) 232 | - Version control hook configurations 233 | - Document custom modifications 234 | 235 | ## Troubleshooting 236 | 237 | ### Hooks not executing 238 | - Check file permissions: `chmod +x *.sh` 239 | - Verify paths in settings.json 240 | - Check Claude Code logs for errors 241 | 242 | ### Security scanner too restrictive 243 | - Review patterns in `config/sensitive-patterns.json` 244 | - Add legitimate patterns to the whitelist 245 | - Check logs for what triggered the block 246 | 247 | ### No sound playing 248 | - Verify sound files exist in `sounds/` directory 249 | - Test audio playback: `.claude/hooks/notify.sh input` 250 | - Check system audio settings 251 | - Ensure you have an audio player installed (afplay, paplay, aplay, pw-play, play, ffplay, or PowerShell on Windows) 252 | 253 | ## Hook Setup Command 254 | 255 | For comprehensive setup verification and testing, use: 256 | 257 | ``` 258 | /hook-setup 259 | ``` 260 | 261 | This command uses multi-agent orchestration to verify installation, check configuration, and run comprehensive tests. See [hook-setup.md](setup/hook-setup.md) for details. 262 | 263 | ## Extension Points 264 | 265 | The kit is designed for extensibility: 266 | 267 | 1. **Custom Hooks**: Add new scripts following the existing patterns 268 | 2. **Event Handlers**: Configure hooks for any Claude Code event 269 | 3. **Pattern Updates**: Modify security patterns for your needs 270 | 4. **Sound Customization**: Replace audio files with your preferences -------------------------------------------------------------------------------- /templates/.claude/hooks/config/sensitive-patterns.json: -------------------------------------------------------------------------------- 1 | { 2 | "patterns": { 3 | "api_keys": [], 4 | "credentials": [ 5 | "password\\s*[:=]\\s*[\"']?[^\\s\"']+[\"']?", 6 | "passwd\\s*[:=]\\s*[\"']?[^\\s\"']+[\"']?", 7 | "secret\\s*[:=]\\s*[\"']?[^\\s\"']+[\"']?", 8 | "private[_-]?key\\s*[:=]\\s*[\"']?[^\\s\"']+[\"']?", 9 | "access[_-]?key\\s*[:=]\\s*[\"']?[^\\s\"']+[\"']?", 10 | "auth[_-]?token\\s*[:=]\\s*[\"']?[^\\s\"']+[\"']?", 11 | "api[_-]?key\\s*[:=]\\s*[\"']?[^\\s\"']+[\"']?", 12 | "client[_-]?secret\\s*[:=]\\s*[\"']?[^\\s\"']+[\"']?" 13 | ], 14 | "sensitive_files": [ 15 | ".env", 16 | ".env.local", 17 | ".env.production", 18 | ".env.development", 19 | ".env.staging", 20 | "credentials.json", 21 | "google-credentials.json", 22 | "service-account.json", 23 | "private.key", 24 | "id_rsa", 25 | "id_ed25519", 26 | "id_dsa", 27 | "id_ecdsa", 28 | ".pem", 29 | ".key", 30 | ".p12", 31 | ".pfx", 32 | "keystore", 33 | ".jks" 34 | ], 35 | "regex_patterns": [ 36 | "sk-[a-zA-Z0-9]{32,}", 37 | "sk-proj-[a-zA-Z0-9]{32,}", 38 | "AIza[0-9A-Za-z\\-_]{35}", 39 | "gsk_[a-zA-Z0-9]{32,}", 40 | "AKIA[0-9A-Z]{16}", 41 | "aws_secret_access_key\\s*=\\s*[a-zA-Z0-9/+=]{40}", 42 | "(postgres|postgresql|mysql|mongodb|redis)://[^:]+:[^@]+@[^/]+", 43 | "-----BEGIN.*(RSA|DSA|EC|OPENSSH|PGP).*PRIVATE KEY-----", 44 | "Bearer\\s+[a-zA-Z0-9\\-_]+\\.[a-zA-Z0-9\\-_]+\\.[a-zA-Z0-9\\-_]+", 45 | "[A-Z_]+(KEY|TOKEN|SECRET|PASSWORD|PASSWD)\\s*=\\s*[\"']?[^\\s\"']+[\"']?", 46 | "(api[_-]?key|access[_-]?token|auth[_-]?token)\\s*[:=]\\s*[\"']?[a-zA-Z0-9_\\-]{20,}[\"']?", 47 | "(password|secret|key)\\s*[:=]\\s*[\"']?[A-Za-z0-9+/]{40,}={0,2}[\"']?", 48 | "ghp_[a-zA-Z0-9]{36}", 49 | "gho_[a-zA-Z0-9]{36}", 50 | "github_pat_[a-zA-Z0-9]{22}_[a-zA-Z0-9]{59}", 51 | "glpat-[a-zA-Z0-9\\-_]{20}", 52 | "xoxb-[0-9]{10,13}-[0-9]{10,13}-[a-zA-Z0-9]{24}", 53 | "sq0atp-[0-9A-Za-z\\-_]{22}", 54 | "sq0csp-[0-9A-Za-z\\-_]{43}", 55 | "SK[a-z0-9]{32}" 56 | ] 57 | }, 58 | "whitelist": { 59 | "allowed_mentions": [ 60 | "GOOGLE_API_KEY=your_google_api_key_here", 61 | "GROQ_API_KEY=your_groq_api_key_here", 62 | "OPENAI_API_KEY=your_openai_api_key_here", 63 | "GEMINI_API_KEY=your_gemini_api_key_here", 64 | "AWS_ACCESS_KEY_ID=your_access_key_here", 65 | "api_key=settings.api_key", 66 | "api_key=process.env.API_KEY", 67 | "api_key=YOUR_API_KEY", 68 | "password=your_password_here", 69 | "password=", 70 | "password=${PASSWORD}", 71 | "token=your_token_here", 72 | "token=", 73 | "secret=your_secret_here", 74 | "Bearer YOUR_TOKEN_HERE", 75 | "Bearer ", 76 | "postgres://user:password@localhost", 77 | "mysql://root:password@localhost", 78 | "mongodb://user:password@localhost", 79 | "redis://user:password@localhost", 80 | "connection_string = \"your_connection_string_here\"", 81 | "API_KEY=", 82 | "SECRET_KEY=", 83 | "DATABASE_URL=" 84 | ] 85 | } 86 | } -------------------------------------------------------------------------------- /templates/.claude/hooks/gemini-context-injector.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | # Gemini Context Injector Hook 3 | # Automatically adds project context files to new Gemini consultation sessions: 4 | # - docs/ai-context/project-structure.md 5 | # - MCP-ASSISTANT-RULES.md 6 | # 7 | # This hook enhances Gemini consultations by automatically including your project's 8 | # structure documentation and assistant rules, ensuring the AI has complete context. 9 | 10 | set -euo pipefail 11 | 12 | SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" 13 | PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)" 14 | PROJECT_STRUCTURE_FILE="$PROJECT_ROOT/docs/ai-context/project-structure.md" 15 | MCP_RULES_FILE="$PROJECT_ROOT/MCP-ASSISTANT-RULES.md" 16 | LOG_FILE="$SCRIPT_DIR/../logs/context-injection.log" 17 | 18 | # Ensure log directory exists 19 | mkdir -p "$(dirname "$LOG_FILE")" 20 | 21 | # Read input from stdin 22 | INPUT_JSON=$(cat) 23 | 24 | # Function to log injection events 25 | log_injection_event() { 26 | local event_type="$1" 27 | local details="$2" 28 | local timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ") 29 | echo "{\"timestamp\": \"$timestamp\", \"event\": \"$event_type\", \"details\": \"$details\"}" >> "$LOG_FILE" 30 | } 31 | 32 | # Main logic 33 | main() { 34 | # Extract tool information from stdin 35 | local tool_name=$(echo "$INPUT_JSON" | jq -r '.tool_name // ""') 36 | 37 | # Only process Gemini consultation requests 38 | if [[ "$tool_name" != "mcp__gemini__consult_gemini" ]]; then 39 | echo '{"continue": true}' 40 | exit 0 41 | fi 42 | 43 | # Extract tool arguments 44 | local tool_args=$(echo "$INPUT_JSON" | jq -r '.tool_input // "{}"') 45 | 46 | # Check if this is a new session (no session_id provided) 47 | local session_id=$(echo "$tool_args" | jq -r '.session_id // ""' 2>/dev/null || echo "") 48 | 49 | if [[ -z "$session_id" || "$session_id" == "null" ]]; then 50 | log_injection_event "new_session_detected" "preparing_context_injection" 51 | 52 | # Check if required files exist 53 | local missing_files="" 54 | if [[ ! -f "$PROJECT_STRUCTURE_FILE" ]]; then 55 | missing_files="$missing_files project_structure.md" 56 | fi 57 | if [[ ! -f "$MCP_RULES_FILE" ]]; then 58 | missing_files="$missing_files MCP-ASSISTANT-RULES.md" 59 | fi 60 | 61 | # If either file is missing, log warning but continue 62 | if [[ -n "$missing_files" ]]; then 63 | log_injection_event "warning" "missing_files:$missing_files" 64 | fi 65 | 66 | # If both files are missing, exit early 67 | if [[ ! -f "$PROJECT_STRUCTURE_FILE" ]] && [[ ! -f "$MCP_RULES_FILE" ]]; then 68 | echo '{"continue": true}' 69 | exit 0 70 | fi 71 | 72 | # Extract current attached_files if any 73 | local current_files=$(echo "$tool_args" | jq -c '.attached_files // []' 2>/dev/null || echo "[]") 74 | 75 | # Check if files are already included 76 | local has_project_structure=$(echo "$current_files" | jq -e ".[] | select(. == \"$PROJECT_STRUCTURE_FILE\")" > /dev/null 2>&1 && echo "true" || echo "false") 77 | local has_mcp_rules=$(echo "$current_files" | jq -e ".[] | select(. == \"$MCP_RULES_FILE\")" > /dev/null 2>&1 && echo "true" || echo "false") 78 | 79 | # If both files exist and are already included, skip 80 | if [[ -f "$PROJECT_STRUCTURE_FILE" ]] && [[ "$has_project_structure" == "true" ]] && \ 81 | [[ -f "$MCP_RULES_FILE" ]] && [[ "$has_mcp_rules" == "true" ]]; then 82 | log_injection_event "skipped" "all_required_files_already_included" 83 | echo '{"continue": true}' 84 | exit 0 85 | fi 86 | 87 | # Add missing files to attached_files 88 | local modified_args="$tool_args" 89 | local files_added="" 90 | 91 | if [[ -f "$PROJECT_STRUCTURE_FILE" ]] && [[ "$has_project_structure" == "false" ]]; then 92 | modified_args=$(echo "$modified_args" | jq --arg file "$PROJECT_STRUCTURE_FILE" ' 93 | .attached_files = ((.attached_files // []) + [$file]) 94 | ' 2>/dev/null) 95 | files_added="$files_added project_structure.md" 96 | fi 97 | 98 | if [[ -f "$MCP_RULES_FILE" ]] && [[ "$has_mcp_rules" == "false" ]]; then 99 | modified_args=$(echo "$modified_args" | jq --arg file "$MCP_RULES_FILE" ' 100 | .attached_files = ((.attached_files // []) + [$file]) 101 | ' 2>/dev/null) 102 | files_added="$files_added MCP-ASSISTANT-RULES.md" 103 | fi 104 | 105 | if [[ -n "$modified_args" ]] && [[ "$modified_args" != "$tool_args" ]]; then 106 | log_injection_event "context_injected" "added_files:$files_added" 107 | 108 | # Update the input JSON with modified tool_input 109 | local output_json=$(echo "$INPUT_JSON" | jq --argjson new_args "$modified_args" '.tool_input = $new_args') 110 | 111 | # Return the modified input to stdout 112 | echo "$output_json" 113 | exit 0 114 | else 115 | log_injection_event "error" "failed_to_modify_arguments" 116 | # Continue without modification on error 117 | echo '{"continue": true}' 118 | exit 0 119 | fi 120 | else 121 | log_injection_event "existing_session" "session_id:$session_id" 122 | # For existing sessions, continue without modification 123 | echo '{"continue": true}' 124 | exit 0 125 | fi 126 | } 127 | 128 | # Run main function 129 | main -------------------------------------------------------------------------------- /templates/.claude/hooks/mcp-security-scan.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | # MCP Security Scanner Hook 3 | # Scans MCP requests for sensitive data before sending to external services 4 | # 5 | # This hook protects against accidental exposure of secrets, API keys, and other 6 | # sensitive information when using MCP servers like Gemini or Context7. 7 | 8 | set -euo pipefail 9 | 10 | SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" 11 | PATTERNS_FILE="$SCRIPT_DIR/config/sensitive-patterns.json" 12 | LOG_FILE="$SCRIPT_DIR/../logs/security-scan.log" 13 | 14 | # Ensure log directory exists 15 | mkdir -p "$(dirname "$LOG_FILE")" 16 | 17 | # Read input from stdin 18 | INPUT_JSON=$(cat) 19 | 20 | # Function to log security events 21 | log_security_event() { 22 | local event_type="$1" 23 | local details="$2" 24 | local tool_name="${3:-unknown}" 25 | local timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ") 26 | echo "{\"timestamp\": \"$timestamp\", \"tool\": \"$tool_name\", \"event\": \"$event_type\", \"details\": \"$details\"}" >> "$LOG_FILE" 27 | } 28 | 29 | # Function to check if content matches sensitive patterns 30 | check_sensitive_content() { 31 | local content="$1" 32 | local pattern_type="$2" 33 | 34 | # Get patterns from JSON config 35 | local patterns=$(jq -r ".patterns.$pattern_type[]" "$PATTERNS_FILE" 2>/dev/null || echo "") 36 | 37 | for pattern in $patterns; do 38 | if echo "$content" | grep -qiE "$pattern"; then 39 | # Check whitelist 40 | local whitelisted=false 41 | local whitelist_patterns=$(jq -r '.whitelist.allowed_mentions[]' "$PATTERNS_FILE" 2>/dev/null || echo "") 42 | 43 | for whitelist in $whitelist_patterns; do 44 | if echo "$content" | grep -qF "$whitelist"; then 45 | whitelisted=true 46 | break 47 | fi 48 | done 49 | 50 | if [[ "$whitelisted" == "false" ]]; then 51 | return 0 # Found sensitive data 52 | fi 53 | fi 54 | done 55 | 56 | return 1 # No sensitive data found 57 | } 58 | 59 | # Function to scan file content 60 | scan_file_content() { 61 | local file_path="$1" 62 | 63 | # Check if file name itself is sensitive 64 | local filename=$(basename "$file_path") 65 | if check_sensitive_content "$filename" "sensitive_files"; then 66 | return 0 # Sensitive file 67 | fi 68 | 69 | # Don't scan files that don't exist or are too large 70 | if [[ ! -f "$file_path" ]] || [[ $(stat -f%z "$file_path" 2>/dev/null || stat -c%s "$file_path" 2>/dev/null || echo "999999999") -gt 1048576 ]]; then 71 | return 1 72 | fi 73 | 74 | # Read and scan file content 75 | local content=$(cat "$file_path" 2>/dev/null || echo "") 76 | 77 | # Check all pattern types 78 | for pattern_type in api_keys credentials regex_patterns; do 79 | if check_sensitive_content "$content" "$pattern_type"; then 80 | return 0 # Found sensitive data 81 | fi 82 | done 83 | 84 | return 1 85 | } 86 | 87 | # Main scanning logic 88 | main() { 89 | # Extract tool information from stdin 90 | local tool_name=$(echo "$INPUT_JSON" | jq -r '.tool_name // ""') 91 | local tool_args=$(echo "$INPUT_JSON" | jq -r '.tool_input // "{}"') 92 | 93 | log_security_event "scan_started" "$tool_name" "$tool_name" 94 | 95 | # Check code_context for sensitive data 96 | local code_context=$(echo "$tool_args" | jq -r '.code_context // ""' 2>/dev/null || echo "") 97 | if [[ -n "$code_context" ]]; then 98 | for pattern_type in api_keys credentials regex_patterns; do 99 | if check_sensitive_content "$code_context" "$pattern_type"; then 100 | log_security_event "blocked" "sensitive_data_in_code_context" "$tool_name" 101 | echo '{"decision": "block", "reason": "Security Alert: Detected sensitive data in code_context. Found patterns matching actual credentials (API keys, passwords, or secrets with values). For discussions about security topics, use placeholders like YOUR_API_KEY, , or example values instead of real credentials."}' 102 | exit 2 103 | fi 104 | done 105 | fi 106 | 107 | # Check problem_description for sensitive data 108 | local problem_desc=$(echo "$tool_args" | jq -r '.problem_description // ""' 2>/dev/null || echo "") 109 | if [[ -n "$problem_desc" ]]; then 110 | for pattern_type in api_keys credentials regex_patterns; do 111 | if check_sensitive_content "$problem_desc" "$pattern_type"; then 112 | log_security_event "blocked" "sensitive_data_in_problem_description" "$tool_name" 113 | echo '{"decision": "block", "reason": "Security Alert: Detected sensitive data in problem description. Found patterns matching actual credentials (API keys, passwords, connection strings, or tokens with values). For security discussions, use placeholders: YOUR_API_KEY, , postgres://user:password@localhost, or example-token-here."}' 114 | exit 2 115 | fi 116 | done 117 | fi 118 | 119 | # Check attached files 120 | local attached_files=$(echo "$tool_args" | jq -r '.attached_files[]?' 2>/dev/null || echo "") 121 | for file in $attached_files; do 122 | if scan_file_content "$file"; then 123 | log_security_event "blocked" "sensitive_file_attached:$file" "$tool_name" 124 | echo "{\"decision\": \"block\", \"reason\": \"Security Alert: Detected sensitive content in attached file $file. Found credentials, private keys, or environment files. Remove actual secrets and use placeholders like YOUR_SECRET_HERE or example values for demonstrations.\"}" 125 | exit 2 126 | fi 127 | done 128 | 129 | # Check specific question for Context7 130 | if [[ "$tool_name" == "mcp__context7__get-library-docs" ]]; then 131 | local library_id=$(echo "$tool_args" | jq -r '.context7CompatibleLibraryID // ""' 2>/dev/null || echo "") 132 | # Basic check to prevent injection attacks 133 | if echo "$library_id" | grep -qE '(\$|`|;|&&|\|\||>|<)'; then 134 | log_security_event "blocked" "suspicious_library_id" "$tool_name" 135 | echo '{"decision": "block", "reason": "Security Alert: Detected suspicious characters in library ID that could indicate command injection. Please use only alphanumeric characters, hyphens, underscores, and forward slashes."}' 136 | exit 2 137 | fi 138 | fi 139 | 140 | log_security_event "scan_completed" "no_sensitive_data_found" "$tool_name" 141 | 142 | # All checks passed, allow the tool to continue 143 | # No output needed when allowing - just exit 0 144 | } 145 | 146 | # Run main function 147 | main -------------------------------------------------------------------------------- /templates/.claude/hooks/notify.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | # Claude Code notification hook script 3 | # Plays pleasant sounds when Claude needs input or completes tasks 4 | 5 | # Get the directory where this script is located 6 | SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" 7 | SOUNDS_DIR="$SCRIPT_DIR/sounds" 8 | 9 | # Function to play a sound file with cross-platform support 10 | play_sound_file() { 11 | local sound_file="$1" 12 | 13 | # Check if file exists 14 | if [[ ! -f "$sound_file" ]]; then 15 | echo "Warning: Sound file not found: $sound_file" >&2 16 | return 1 17 | fi 18 | 19 | # Detect OS and use appropriate command-line audio player 20 | local os_type="$(uname -s)" 21 | 22 | case "$os_type" in 23 | Darwin*) # macOS 24 | if command -v afplay &> /dev/null; then 25 | afplay "$sound_file" 2>/dev/null & 26 | return 0 # Exit immediately after starting playback 27 | fi 28 | ;; 29 | 30 | Linux*) # Linux 31 | # Try PulseAudio first (most common on modern desktop Linux) 32 | if command -v paplay &> /dev/null; then 33 | paplay "$sound_file" 2>/dev/null & 34 | return 0 # Exit immediately after starting playback 35 | fi 36 | 37 | # Try ALSA 38 | if command -v aplay &> /dev/null; then 39 | aplay -q "$sound_file" 2>/dev/null & 40 | return 0 # Exit immediately after starting playback 41 | fi 42 | 43 | # Try PipeWire (newer systems) 44 | if command -v pw-play &> /dev/null; then 45 | pw-play "$sound_file" 2>/dev/null & 46 | return 0 # Exit immediately after starting playback 47 | fi 48 | 49 | # Try sox play command 50 | if command -v play &> /dev/null; then 51 | play -q "$sound_file" 2>/dev/null & 52 | return 0 # Exit immediately after starting playback 53 | fi 54 | ;; 55 | 56 | MINGW*|CYGWIN*|MSYS*) # Windows (Git Bash, WSL, etc.) 57 | # Try PowerShell 58 | if command -v powershell.exe &> /dev/null; then 59 | # Use Windows Media Player COM object for better compatibility 60 | # Run in background and exit immediately 61 | powershell.exe -NoProfile -Command " 62 | Start-Job -ScriptBlock { 63 | \$player = New-Object -ComObject WMPlayer.OCX 64 | \$player.URL = '$sound_file' 65 | \$player.controls.play() 66 | Start-Sleep -Milliseconds 1000 67 | \$player.close() 68 | } 69 | " 2>/dev/null 70 | return 0 # Exit immediately after starting playback 71 | fi 72 | ;; 73 | esac 74 | 75 | # If we have ffplay (cross-platform) 76 | if command -v ffplay &> /dev/null; then 77 | ffplay -nodisp -autoexit -loglevel quiet "$sound_file" 2>/dev/null & 78 | return 0 # Exit immediately after starting playback 79 | fi 80 | 81 | # No audio player found - fail silently 82 | return 1 83 | } 84 | 85 | # Main script logic 86 | case "$1" in 87 | "input") 88 | play_sound_file "$SOUNDS_DIR/input-needed.wav" 89 | ;; 90 | 91 | "complete") 92 | play_sound_file "$SOUNDS_DIR/complete.wav" 93 | ;; 94 | 95 | *) 96 | echo "Usage: $0 {input|complete}" >&2 97 | echo " input - Play sound when Claude needs user input" >&2 98 | echo " complete - Play sound when Claude completes tasks" >&2 99 | exit 1 100 | ;; 101 | esac 102 | 103 | exit 0 -------------------------------------------------------------------------------- /templates/.claude/hooks/setup/hook-setup.md: -------------------------------------------------------------------------------- 1 | ## Description 2 | 3 | This command uses specialized agents to verify, configure, and test your Claude Code hooks installation. It ensures everything is properly set up and working correctly. 4 | 5 | ## Process 6 | 7 | ### Phase 1: Multi-Agent Setup Verification 8 | 9 | The command spawns specialized agents to handle different aspects: 10 | 11 | 1. **Installation Agent** 12 | - Verifies `.claude/hooks/` directory exists 13 | - Checks all hook scripts are present 14 | - Ensures executable permissions (`chmod +x`) 15 | - Validates sound files and configuration files 16 | 17 | 2. **Configuration Agent** 18 | - Locates Claude Code settings.json for your OS 19 | - Verifies hook configurations in settings 20 | - Checks WORKSPACE environment variable 21 | - Validates MCP server configurations 22 | 23 | 3. **Documentation Agent** 24 | - Ensures project structure documentation exists 25 | - Verifies paths used by context injector 26 | - Checks log directory setup 27 | 28 | ### Phase 2: Comprehensive Testing 29 | 30 | After setup verification, the main agent runs comprehensive tests: 31 | 32 | 1. **Security Scanner Tests** 33 | - API key detection patterns 34 | - Password and secret detection 35 | - Whitelist functionality 36 | - Command injection protection 37 | - File scanning capabilities 38 | 39 | 2. **Context Injector Tests** 40 | - New session detection 41 | - File attachment logic 42 | - Path resolution 43 | - Error handling scenarios 44 | 45 | 3. **Notification Tests** 46 | - Audio playback on current platform 47 | - Fallback mechanism verification 48 | - Both input and complete sounds 49 | 50 | ## Expected Output 51 | 52 | ``` 53 | Starting multi-agent hook setup verification... 54 | 55 | [Installation Agent] 56 | ✓ Hooks directory found: .claude/hooks/ 57 | ✓ All hook scripts present and executable 58 | ✓ Configuration files valid 59 | ✓ Sound files present 60 | 61 | [Configuration Agent] 62 | ✓ Project settings found: .claude/settings.json 63 | ✓ Hook configurations verified 64 | ✓ WORKSPACE environment variable set correctly 65 | 66 | [Documentation Agent] 67 | ✓ Project structure documentation found 68 | ✓ Log directories configured 69 | 70 | Running comprehensive tests... 71 | 72 | [Security Scanner] 73 | ✓ Detected: sk-1234567890abcdef (API key) 74 | ✓ Detected: password=mysecret123 75 | ✓ Allowed: YOUR_API_KEY (whitelisted) 76 | ✓ Blocked: $(malicious) (injection attempt) 77 | 78 | [Context Injector] 79 | ✓ New session handling correct 80 | ✓ File attachment working 81 | ✓ Error handling graceful 82 | 83 | [Notifications] 84 | ✓ Audio playback successful 85 | ✓ Platform: darwin (macOS) 86 | 87 | All hooks configured and tested successfully! 88 | ``` 89 | 90 | ## Troubleshooting 91 | 92 | The command provides specific guidance for any issues found: 93 | - Missing files or permissions 94 | - Configuration problems 95 | - Test failures with debugging steps 96 | - Platform-specific audio issues -------------------------------------------------------------------------------- /templates/.claude/hooks/setup/settings.json.template: -------------------------------------------------------------------------------- 1 | { 2 | "hooks": { 3 | "PreToolUse": [ 4 | { 5 | "matcher": "mcp__gemini__consult_gemini", 6 | "hooks": [ 7 | { 8 | "type": "command", 9 | "command": "${WORKSPACE}/.claude/hooks/gemini-context-injector.sh", 10 | "description": "Automatically adds project structure to new Gemini sessions" 11 | } 12 | ] 13 | }, 14 | { 15 | "matcher": "mcp__.*", 16 | "hooks": [ 17 | { 18 | "type": "command", 19 | "command": "${WORKSPACE}/.claude/hooks/mcp-security-scan.sh", 20 | "description": "Scans for sensitive data before sending to external services" 21 | } 22 | ] 23 | }, 24 | { 25 | "matcher": "Task", 26 | "hooks": [ 27 | { 28 | "type": "command", 29 | "command": "${WORKSPACE}/.claude/hooks/subagent-context-injector.sh", 30 | "description": "Automatically adds project context to sub-agent prompts" 31 | } 32 | ] 33 | } 34 | ], 35 | "Notification": [ 36 | { 37 | "matcher": ".*", 38 | "hooks": [ 39 | { 40 | "type": "command", 41 | "command": "${WORKSPACE}/.claude/hooks/notify.sh input", 42 | "description": "Plays sound when Claude needs user input" 43 | } 44 | ] 45 | } 46 | ], 47 | "Stop": [ 48 | { 49 | "matcher": ".*", 50 | "hooks": [ 51 | { 52 | "type": "command", 53 | "command": "${WORKSPACE}/.claude/hooks/notify.sh complete", 54 | "description": "Plays sound when Claude completes tasks" 55 | } 56 | ] 57 | } 58 | ] 59 | }, 60 | "environment": { 61 | "WORKSPACE": "/path/to/your/project" 62 | } 63 | } -------------------------------------------------------------------------------- /templates/.claude/hooks/sounds/complete.wav: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cfrs2005/claude-init/625a782009998a3aa046c7d02a143409f2231fce/templates/.claude/hooks/sounds/complete.wav -------------------------------------------------------------------------------- /templates/.claude/hooks/sounds/input-needed.wav: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cfrs2005/claude-init/625a782009998a3aa046c7d02a143409f2231fce/templates/.claude/hooks/sounds/input-needed.wav -------------------------------------------------------------------------------- /templates/.claude/hooks/subagent-context-injector.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | # Sub-Agent Context Auto-Loader 3 | # Automatically enhances Task tool prompts with essential project context 4 | # 5 | # This hook ensures every sub-agent spawned via the Task tool automatically 6 | # receives core project documentation, eliminating the need to manually 7 | # include context in each Task prompt. 8 | # 9 | # IMPLEMENTATION OVERVIEW: 10 | # - Registered as a PreToolUse hook in .claude/settings.json 11 | # - Intercepts all Task tool calls before execution 12 | # - Injects references to CLAUDE.md, project-structure.md, and docs-overview.md 13 | # - Preserves original prompt by prepending context, not replacing 14 | # - Passes through non-Task tools unchanged with {"continue": true} 15 | 16 | 17 | set -euo pipefail 18 | 19 | SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" 20 | PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)" 21 | 22 | # Read input from stdin 23 | INPUT_JSON=$(cat) 24 | 25 | # Extract tool information 26 | tool_name=$(echo "$INPUT_JSON" | jq -r '.tool_name // ""') 27 | 28 | # Only process Task tool calls - pass through all other tools unchanged 29 | if [[ "$tool_name" != "Task" ]]; then 30 | echo '{"continue": true}' 31 | exit 0 32 | fi 33 | 34 | # Extract current prompt from the Task tool input 35 | current_prompt=$(echo "$INPUT_JSON" | jq -r '.tool_input.prompt // ""') 36 | 37 | # Build context injection header with project documentation references 38 | # These files are automatically available to all sub-agents via @ references 39 | context_injection="## Auto-Loaded Project Context 40 | 41 | This sub-agent has automatic access to the following project documentation: 42 | - @$PROJECT_ROOT/docs/CLAUDE.md (Project overview, coding standards, and AI instructions) 43 | - @$PROJECT_ROOT/docs/ai-context/project-structure.md (Complete file tree and tech stack) 44 | - @$PROJECT_ROOT/docs/ai-context/docs-overview.md (Documentation architecture) 45 | 46 | These files provide essential context about the project structure, 47 | conventions, and development patterns. Reference them as needed for your task. 48 | 49 | --- 50 | 51 | ## Your Task 52 | 53 | " 54 | 55 | # Combine context injection with original prompt 56 | # The context is prepended to preserve the original task instructions 57 | modified_prompt="${context_injection}${current_prompt}" 58 | 59 | # Update the input JSON with the modified prompt 60 | # This maintains all other tool input fields unchanged 61 | output_json=$(echo "$INPUT_JSON" | jq --arg new_prompt "$modified_prompt" '.tool_input.prompt = $new_prompt') 62 | 63 | # Output the modified JSON for Claude Code to process 64 | # The Task tool will receive the enhanced prompt with context 65 | echo "$output_json" -------------------------------------------------------------------------------- /templates/CLAUDE.md: -------------------------------------------------------------------------------- 1 | # [项目名称] - Claude Code AI 上下文文件 (claude-master) 2 | 3 | ## 1. 项目概览 4 | - **愿景：** [描述项目的愿景和目标] 5 | - **当前阶段：** [当前开发阶段和状态] 6 | - **核心架构：** [高层架构描述] 7 | - **开发策略：** [开发方法和策略说明] 8 | 9 | ## 2. 项目结构 10 | 11 | **⚠️ 重要：AI 智能体在执行任何任务前，必须先阅读[项目结构文档](/docs/ai-context/project-structure.md)，了解完整的技术栈、文件树和项目组织方式。** 12 | 13 | [项目名称]遵循[描述架构模式]。完整的技术栈和文件树结构，请参见[docs/ai-context/project-structure.md](/docs/ai-context/project-structure.md)。 14 | 15 | ## 3. 编码规范与 AI 指令 16 | 17 | ### 通用指令 18 | - 你最重要的工作是管理自己的上下文。在规划变更前，务必先阅读相关文件。 19 | - 更新文档时，保持更新简洁明了，防止内容冗余。 20 | - 编写代码遵循 KISS、YAGNI 和 DRY 原则。 21 | - 有疑问时遵循经过验证的最佳实践。 22 | - 未经用户批准不要提交到 git。 23 | - 不要运行任何服务器，而是告诉用户运行服务器进行测试。 24 | - 优先考虑行业标准库/框架，而不是自定义实现。 25 | - 永远不要模拟任何东西。永远不要使用占位符。永远不要省略代码。 26 | - 相关时应用 SOLID 原则。使用现代框架特性而不是重新发明解决方案。 27 | - 对想法的好坏要坦率诚实。 28 | - 让副作用明确且最小化。 29 | - 设计数据库模式要便于演进（避免破坏性变更）。 30 | 31 | ### 文件组织与模块化 32 | - 默认创建多个小而专注的文件，而不是大而单一的文件 33 | - 每个文件应该有单一职责和明确目的 34 | - 尽可能保持文件在 350 行以内 - 通过提取工具、常量、类型或逻辑组件到单独模块来拆分大文件 35 | - 分离关注点：工具、常量、类型、组件和业务逻辑到不同文件 36 | - 优先组合而非继承 - 只在真正的 'is-a' 关系中使用继承，在 'has-a' 或行为混合时优先组合 37 | 38 | - 遵循现有项目结构和约定 - 将文件放在适当目录。必要时创建新目录并移动文件。 39 | - 使用定义明确的子目录保持组织和可扩展性 40 | - 用清晰的文件夹层次和一致的命名约定构建项目 41 | - 正确导入/导出 - 为可重用性和可维护性而设计 42 | 43 | ### 类型提示（必需） 44 | - **始终**为函数参数和返回值使用类型提示 45 | - 对复杂类型使用 `from typing import` 46 | - 优先使用 `Optional[T]` 而不是 `Union[T, None]` 47 | - 对数据结构使用 Pydantic 模型 48 | 49 | ```python 50 | # 良好示例 51 | from typing import Optional, List, Dict, Tuple 52 | 53 | async def process_audio( 54 | audio_data: bytes, 55 | session_id: str, 56 | language: Optional[str] = None 57 | ) -> Tuple[bytes, Dict[str, Any]]: 58 | """通过管道处理音频。""" 59 | pass 60 | ``` 61 | 62 | ### 命名约定 63 | - **类**：PascalCase（例如 `VoicePipeline`） 64 | - **函数/方法**：snake_case（例如 `process_audio`） 65 | - **常量**：UPPER_SNAKE_CASE（例如 `MAX_AUDIO_SIZE`） 66 | - **私有方法**：前导下划线（例如 `_validate_input`） 67 | - **Pydantic 模型**：PascalCase 带 `Schema` 后缀（例如 `ChatRequestSchema`、`UserSchema`） 68 | 69 | ### 文档要求 70 | - 每个模块需要文档字符串 71 | - 每个公共函数需要文档字符串 72 | - 使用 Google 风格的文档字符串 73 | - 在文档字符串中包含类型信息 74 | 75 | ```python 76 | def calculate_similarity(text1: str, text2: str) -> float: 77 | """计算两个文本间的语义相似度。 78 | 79 | Args: 80 | text1: 要比较的第一个文本 81 | text2: 要比较的第二个文本 82 | 83 | Returns: 84 | 0 到 1 之间的相似度分数 85 | 86 | Raises: 87 | ValueError: 如果任一文本为空 88 | """ 89 | pass 90 | ``` 91 | 92 | ### 安全优先 93 | - 永远不要信任外部输入 - 在边界处验证一切 94 | - 将秘钥保存在环境变量中，永远不要在代码中 95 | - 记录安全事件（登录尝试、认证失败、速率限制、权限拒绝），但永远不要记录敏感数据（音频、对话内容、令牌、个人信息） 96 | - 在 API 网关级别认证用户 - 永远不要信任客户端令牌 97 | - 使用行级安全（RLS）在用户间强制数据隔离 98 | - 设计认证以在所有客户端类型间一致工作 99 | - 为你的平台使用安全的认证模式 100 | - 在创建会话前在服务器端验证所有认证令牌 101 | - 在存储或处理前清理所有用户输入 102 | 103 | ### 错误处理 104 | - 使用具体异常而不是泛型异常 105 | - 始终记录带上下文的错误 106 | - 提供有用的错误消息 107 | - 安全地失败 - 错误不应该暴露系统内部 108 | 109 | ### 可观测系统与日志标准 110 | - 每个请求都需要关联 ID 用于调试 111 | - 为机器而不是人类构建日志 - 使用 JSON 格式，带一致字段（时间戳、级别、关联 ID、事件、上下文）用于自动化分析 112 | - 使跨服务边界的调试成为可能 113 | 114 | ### 状态管理 115 | - 每个状态片段有一个真相来源 116 | - 让状态变更明确且可追踪 117 | - 为多服务语音处理而设计 - 使用会话 ID 进行状态协调，避免在服务器内存中存储对话数据 118 | - 保持对话历史轻量（文本，不是音频） 119 | 120 | ### API 设计原则 121 | - 带一致 URL 模式的 RESTful 设计 122 | - 正确使用 HTTP 状态码 123 | - 从第一天就版本化 API（/v1/、/v2/） 124 | - 为列表端点支持分页 125 | - 使用一致的 JSON 响应格式： 126 | - 成功：`{ "data": {...}, "error": null }` 127 | - 错误：`{ "data": null, "error": {"message": "...", "code": "..."} }` 128 | 129 | ## 4. 多智能体工作流与上下文注入 130 | 131 | ### 子智能体的自动上下文注入 132 | 当使用 Task 工具生成子智能体时，核心项目上下文（CLAUDE.md、project-structure.md、docs-overview.md）会通过 subagent-context-injector hook 自动注入到它们的提示中。这确保所有子智能体都能立即访问基本项目文档，无需在每个 Task 提示中手动指定。 133 | 134 | ## 5. MCP 服务器集成 135 | 136 | ### Gemini 咨询服务器 137 | **使用场景：** 138 | - 需要深度分析或多种方法的复杂编码问题 139 | - 代码审查和架构讨论 140 | - 跨多个文件调试复杂问题 141 | - 性能优化和重构指导 142 | - 复杂实现的详细解释 143 | - 高度安全相关任务 144 | 145 | **自动上下文注入：** 146 | - 套件的 `gemini-context-injector.sh` hook 自动为新会话包含两个关键文件： 147 | - `/docs/ai-context/project-structure.md` - 完整项目结构和技术栈 148 | - `/MCP-ASSISTANT-RULES.md` - 项目特定编码标准和指导原则 149 | - 这确保 Gemini 始终全面理解你的技术栈、架构和项目标准 150 | 151 | **使用模式：** 152 | ```python 153 | # 新咨询会话（项目结构由 hooks 自动附加） 154 | mcp__gemini__consult_gemini( 155 | specific_question="我应该如何优化这个语音管道？", 156 | problem_description="需要减少实时音频处理中的延迟", 157 | code_context="当前管道顺序处理音频...", 158 | attached_files=[ 159 | "src/core/pipelines/voice_pipeline.py" # 你的具体文件 160 | ], 161 | preferred_approach="optimize" 162 | ) 163 | 164 | # 在现有会话中跟进 165 | mcp__gemini__consult_gemini( 166 | specific_question="内存使用怎么办？", 167 | session_id="session_123", 168 | additional_context="实现了你的建议，现在看到高内存使用" 169 | ) 170 | ``` 171 | 172 | **关键能力：** 173 | - 带上下文保持的持续对话会话 174 | - 多文件分析的文件附加和缓存 175 | - 专门的辅助模式（解决、审查、调试、优化、解释） 176 | - 复杂多步问题的会话管理 177 | 178 | **重要：**将 Gemini 的响应作为咨询反馈对待。批判性评估建议，将有价值的洞察整合到你的解决方案中，然后继续实现。 179 | 180 | ### Context7 文档服务器 181 | **仓库**：[Context7 MCP 服务器](https://github.com/upstash/context7) 182 | 183 | **使用场景：** 184 | - 使用外部库/框架（React、FastAPI、Next.js 等） 185 | - 需要超出训练截止日期的当前文档 186 | - 实现与第三方工具的新集成或功能 187 | - 排查库特定问题 188 | 189 | **使用模式：** 190 | ```python 191 | # 将库名解析为 Context7 ID 192 | mcp__context7__resolve_library_id(libraryName="react") 193 | 194 | # 获取焦点文档 195 | mcp__context7__get_library_docs( 196 | context7CompatibleLibraryID="/facebook/react", 197 | topic="hooks", 198 | tokens=8000 199 | ) 200 | ``` 201 | 202 | **关键能力：** 203 | - 最新库文档访问 204 | - 主题焦点文档检索 205 | - 支持特定库版本 206 | - 与当前开发实践集成 207 | 208 | ## 6. 任务完成后协议 209 | 完成任何编码任务后，遵循此检查清单： 210 | 211 | ### 1. 类型安全与质量检查 212 | 根据修改内容运行适当命令： 213 | - **Python 项目**：运行 mypy 类型检查 214 | - **TypeScript 项目**：运行 tsc --noEmit 215 | - **其他语言**：运行适当的代码检查/类型检查工具 216 | 217 | ### 2. 验证 218 | - 确保所有类型检查通过后再认为任务完成 219 | - 如果发现类型错误，在标记任务完成前修复它们 220 | 221 | # 重要指令提醒 222 | 按要求做；不多不少。 223 | 除非绝对必要以实现目标，否则永远不要创建文件。 224 | 始终优先编辑现有文件而不是创建新文件。 225 | 除非用户明确要求，否则永远不要主动创建文档文件（*.md）或 README 文件。只有在用户明确要求时才创建文档文件。 -------------------------------------------------------------------------------- /templates/MCP-ASSISTANT-RULES.md: -------------------------------------------------------------------------------- 1 | # MCP 助手规则 - [项目名称] 2 | 3 | ## 项目上下文 4 | [简要描述你的项目功能和主要目的。保持简洁 - 最多2-3句话。] 5 | 6 | ### 核心愿景与架构 7 | - **产品目标**：[产品的主要目标] 8 | - **目标平台**：[主要平台 - web、移动端、桌面等] 9 | - **架构**：[高层架构概述] 10 | - **关键技术**：[使用的主要技术/框架] 11 | 12 | ### 关键技术原则 13 | [列出指导项目的4-6个核心技术原则] 14 | - **示例**：基于会话的架构，边界清晰 15 | - **示例**：API 优先设计，从第一天开始版本化 16 | - **示例**：默认安全 - 在边界处验证所有输入 17 | - **示例**：可观测系统，结构化日志记录 18 | 19 | **注意：**完整的项目结构和技术栈在附加的 `project-structure.md` 文件中提供。 20 | 21 | ## 关键项目标准 22 | 23 | ### 核心原则 24 | [列出你的基本开发原则] 25 | - 遵循 KISS、YAGNI 和 DRY - 优先选择经过验证的解决方案而不是自定义实现 26 | - 永远不要模拟、使用占位符或省略代码 - 始终完全实现 27 | - 对想法的好坏要坦率诚实 28 | - [添加项目特定原则] 29 | 30 | ### 代码组织 31 | [定义你的代码组织标准] 32 | - 保持文件在 [X] 行以内 - 通过提取工具、常量、类型来拆分 33 | - 每个文件单一职责，目的明确 34 | - 优先组合而非继承 35 | - [添加特定语言/框架的组织规则] 36 | 37 | ### [语言] 标准 38 | [替换为你的主要语言及其标准] 39 | - 类型安全要求 40 | - 命名约定（类、函数、常量） 41 | - 文档要求（docstring 风格、必需元素） 42 | - 错误处理模式 43 | 44 | ### 错误处理与日志记录 45 | - 使用具体异常，提供有用消息 46 | - 仅结构化日志记录 - 定义你的日志记录方法 47 | - [指定日志记录类别或模式] 48 | - 每个请求都需要关联 ID 用于追踪 49 | 50 | ### API 设计 51 | [如适用 - 定义 API 标准] 52 | - RESTful，URL 模式一致 53 | - 从第一天开始版本化（/v1/、/v2/） 54 | - 一致的响应格式 55 | - 正确的 HTTP 状态码 56 | 57 | ### 安全与状态 58 | - 永远不要信任外部输入 - 在边界处验证 59 | - [定义会话/状态管理方法] 60 | - [指定数据保留策略] 61 | - 仅在环境变量中保存秘钥 62 | 63 | ## 项目特定指南 64 | [添加 AI 助手应该知道的任何项目特定指南] 65 | 66 | ### 领域特定规则 67 | [添加特定于你问题领域的规则] 68 | 69 | ### 集成点 70 | [列出关键集成点或外部服务] 71 | 72 | ### 性能考虑 73 | [添加任何性能关键方面] 74 | 75 | ## 重要约束 76 | - 你不能创建、修改或执行代码 77 | - 你在只读支持能力中运作 78 | - 你的建议是给主要 AI（Claude Code）实现的 79 | - 专注于分析、理解和咨询支持 80 | 81 | ## 快速参考 82 | [添加经常需要的信息] 83 | - 关键命令：[列出常用命令] 84 | - 重要路径：[列出关键文件路径] 85 | - 文档链接：[添加详细文档链接] -------------------------------------------------------------------------------- /templates/docs/CONTEXT-tier2-component.md: -------------------------------------------------------------------------------- 1 | # [组件名称] - 组件上下文（第2层） 2 | 3 | > **注意**：这是组件特定上下文。参见根目录 **CLAUDE.md** 了解主项目上下文和编码标准。 4 | 5 | ## 用途 6 | [简要描述此组件在系统中的作用。它解决什么问题，如何融入整体架构？] 7 | 8 | ## 当前状态：[状态描述] ✅/🚧/📋 9 | [当前实现状态，什么在工作，什么在进行中，以及实现的关键里程碑] 10 | 11 | ## 组件特定开发指南 12 | - **[技术/框架]**：[此组件的特定技术要求] 13 | - **[架构模式]**：[组件特定架构方法] 14 | - **[代码组织]**：[此组件内代码应如何结构化] 15 | - **[集成模式]**：[此组件如何与其他组件集成] 16 | - **[质量标准]**：[组件特定质量要求] 17 | 18 | ## 关键组件结构 19 | 20 | ### 核心模块 (`[路径]/`) 21 | - **[模块1]/** - [用途和关键功能] 22 | - **[文件1].[扩展名]** - [特定文件用途和关键特性] 23 | - **[文件2].[扩展名]** - [特定文件用途和关键特性] 24 | - **[模块2]/** - [用途和关键功能] 25 | - **[模块3]/** - [用途和关键功能] 26 | 27 | ### [辅助结构] (`[路径]/`) 28 | - **[组件].[扩展名]** - [组件用途和架构模式] 29 | - **[工具].[扩展名]** - [工具函数和辅助器] 30 | - **[配置].[扩展名]** - [配置和设置管理] 31 | 32 | ### [集成层] (`[路径]/`) 33 | - **[集成1].[扩展名]** - [外部服务集成模式] 34 | - **[集成2].[扩展名]** - [组件间通信] 35 | 36 | ## 实现亮点 37 | 38 | ### [关键特性1] 39 | - **[技术实现]**：[此特性如何实现] 40 | - **[架构决策]**：[为什么选择这种方法] 41 | - **[性能考虑]**：[优化细节] 42 | - **[集成点]**：[如何连接到其他组件] 43 | 44 | ### [关键特性2] 45 | - **[实现模式]**：[技术实现方法] 46 | - **[质量措施]**：[测试、监控、错误处理] 47 | - **[可扩展性考虑]**：[如何处理增长/负载] 48 | 49 | ### [关键特性3] 50 | - **[技术细节]**：[实现细节] 51 | - **[依赖关系]**：[外部依赖和集成点] 52 | - **[配置]**：[如何配置和自定义] 53 | 54 | ## 关键实现细节 55 | 56 | ### [技术模式1] 57 | **[模式描述]**：[此模式解决什么问题] 58 | 59 | ```[语言] 60 | // 显示模式的实现示例 61 | [演示关键实现的代码示例] 62 | ``` 63 | 64 | ### [技术模式2] 65 | **[架构决策]**：[为什么选择这种方法] 66 | 67 | ```[语言] 68 | // 显示架构实现的代码示例 69 | [演示架构的代码示例] 70 | ``` 71 | 72 | ### [集成模式] 73 | **[集成描述]**：[此组件如何与其他组件集成] 74 | 75 | ```[语言] 76 | // 集成实现示例 77 | [显示集成模式的代码示例] 78 | ``` 79 | 80 | ## 开发注意事项 81 | 82 | ### [当前挑战] 83 | - **[挑战1]**：[描述和当前方法] 84 | - **[挑战2]**：[描述和缓解策略] 85 | 86 | ### [未来考虑] 87 | - **[增强1]**：[计划改进和理由] 88 | - **[增强2]**：[未来架构演进] 89 | 90 | ### [性能指标] 91 | - **[关键指标1]**：[当前性能和目标] 92 | - **[关键指标2]**：[监控和优化方法] 93 | 94 | --- 95 | 96 | *此组件文档为 [组件名称] 内的 AI 辅助开发提供上下文。有关系统级模式和标准，请参考主 CLAUDE.md 文件。* -------------------------------------------------------------------------------- /templates/docs/CONTEXT-tier3-feature.md: -------------------------------------------------------------------------------- 1 | # [功能名称] 文档（第3层） 2 | 3 | *此文件记录 [组件名称] 内的 [功能/模块] 模式、架构决策和实现。* 4 | 5 | ## [功能] 架构概述 6 | 7 | ### [架构决策标题] 8 | 9 | **背景**：[导致此架构决策的情况] 10 | 11 | **决策**：[决定和实现的内容] 12 | 13 | **理由**： 14 | - **[优势1]**：[为什么这种方法提供此优势] 15 | - **[优势2]**：[技术或业务优势] 16 | - **[优势3]**：[性能或可维护性优势] 17 | - **[优势4]**：[开发者体验或运营优势] 18 | 19 | **后果**： 20 | - [此决策的积极结果] 21 | - [实现的技术改进] 22 | - [运营或维护优势] 23 | - [用户体验增强] 24 | 25 | ## [功能] 实现模式 26 | 27 | ### [实现模式1] 28 | 29 | **文件组织**： 30 | ``` 31 | [功能目录]/ 32 | ├── [文件1].[扩展名] # [用途和职责] 33 | ├── [文件2].[扩展名] # [用途和职责] 34 | ├── [文件3].[扩展名] # [用途和职责] 35 | └── [文件4].[扩展名] # [用途和职责] 36 | ``` 37 | 38 | **架构优势**： 39 | - **[优势1]**：[此组织如何提供此优势] 40 | - **[优势2]**：[此结构的技术优势] 41 | - **[优势3]**：[可维护性或可扩展性优势] 42 | - **[优势4]**：[开发者体验改进] 43 | 44 | ### [实现模式2] 45 | 46 | **架构决策**：[采用的技术方法] 47 | 48 | **背景**：[导致此方法的背景和需求] 49 | 50 | **决策**：[做出的具体实现选择] 51 | 52 | **理由**： 53 | - **[技术原因]**：[为什么这是最佳技术选择] 54 | - **[性能原因]**：[性能优势] 55 | - **[可维护性原因]**：[长期维护优势] 56 | - **[集成原因]**：[如何与其他组件集成] 57 | 58 | **实现细节**： 59 | ```[语言] 60 | // [此代码演示内容的描述] 61 | [显示实现模式的详细代码示例] 62 | ``` 63 | 64 | ### [实现模式3] 65 | 66 | **[模式名称]**：[模式的描述] 67 | 68 | ```[语言] 69 | // [代码示例标题] 70 | [显示模式实际应用的综合代码示例] 71 | ``` 72 | 73 | **实现优势**： 74 | - **[优势1]**：[此实现提供的具体优势] 75 | - **[优势2]**：[性能或可靠性改进] 76 | - **[优势3]**：[开发者体验增强] 77 | 78 | ## [技术领域] 实现 79 | 80 | ### [技术特性1] 81 | 82 | **[特性描述]**：[此特性的功能和重要性] 83 | 84 | **架构模式**： 85 | ```[语言] 86 | // [架构方法的描述] 87 | [演示架构的代码示例] 88 | ``` 89 | 90 | **关键实现细节**： 91 | - **[细节1]**：[重要实现考虑] 92 | - **[细节2]**：[技术约束或优化] 93 | - **[细节3]**：[集成或性能考虑] 94 | 95 | ### [技术特性2] 96 | 97 | **实现方法**：[此特性如何实现] 98 | 99 | ```[语言] 100 | // [代码示例描述] 101 | [详细实现示例] 102 | ``` 103 | 104 | **技术考虑**： 105 | - **[考虑1]**：[重要技术因素] 106 | - **[考虑2]**：[性能或可扩展性因素] 107 | - **[考虑3]**：[维护或测试考虑] 108 | 109 | ## [集成/通信] 模式 110 | 111 | ### [集成模式1] 112 | 113 | **背景**：[何时以及为什么使用此集成模式] 114 | 115 | **实现**： 116 | ```[语言] 117 | // [集成示例描述] 118 | [显示集成实现的代码] 119 | ``` 120 | 121 | **优势**： 122 | - **[集成优势1]**：[如何改进系统集成] 123 | - **[集成优势2]**：[性能或可靠性改进] 124 | 125 | ### [集成模式2] 126 | 127 | **模式描述**：[此集成模式解决什么问题] 128 | 129 | ```[语言] 130 | // [集成代码示例] 131 | [显示集成模式的实现] 132 | ``` 133 | 134 | ## 性能与优化细节 135 | 136 | ### [性能优化1] 137 | **优化**：[优化了什么以及如何优化] 138 | - **之前**：[以前的性能特性] 139 | - **之后**：[改进的性能指标] 140 | - **实现**：[如何实现优化] 141 | 142 | ### [性能优化2] 143 | **技术改进**：[具体性能增强] 144 | - **影响**：[实现的可测量改进] 145 | - **方法**：[使用的技术方法] 146 | - **权衡**：[为优化做出的任何妥协] 147 | 148 | ## 错误处理与边缘情况 149 | 150 | ### [错误场景1] 151 | **场景**：[此处理的错误条件] 152 | **处理**：[如何检测和管理错误] 153 | **恢复**：[系统如何从此错误中恢复] 154 | 155 | ### [错误场景2] 156 | **边缘情况**：[需要处理的异常条件] 157 | **解决方案**：[实现如何处理此情况] 158 | **验证**：[如何测试或验证此处理] 159 | 160 | --- 161 | 162 | *此功能文档为 AI 辅助开发提供详细实现上下文。有关更广泛的组件上下文，请参见组件级 CONTEXT.md 文件。* -------------------------------------------------------------------------------- /templates/docs/README.md: -------------------------------------------------------------------------------- 1 | # 文档系统指南 2 | 3 | 本指南解释了三层文档架构如何为 Claude Code 开发套件提供支持，以及为什么它比传统文档方法提供更优秀的结果。 4 | 5 | ## 关键基础文件 6 | 7 | 两个文件构成了整个文档系统的基石： 8 | 9 | 1. **docs-overview.md** - 中央路由指南，根据任务复杂性引导 AI 智能体到适当的文档。此文件映射你的整个文档结构，启用智能上下文加载。 10 | 11 | 2. **project-structure.md** - 项目完整文件结构和技术栈的综合概述。此文件是所有 AI 智能体的必读文件，必须附加到 Gemini 咨询中。 12 | 13 | 这些基础文件确保 AI 智能体始终具备理解项目和导航到相关文档所需的基本上下文。 14 | 15 | ## 为什么选择三层系统 16 | 17 | ### 传统文档问题 18 | 19 | 标准文档方法为 AI 辅助开发创造了摩擦： 20 | 21 | - **上下文过载** - AI 智能体必须为简单任务处理整个文档集 22 | - **维护负担** - 每个代码更改都会级联到多个文档位置 23 | - **陈旧内容** - 文档与实现现实分离 24 | - **无 AI 优化** - 人类可读格式缺乏机器处理结构 25 | 26 | ### 三层解决方案 27 | 28 | 套件通过分层组织解决这些问题： 29 | 30 | **第1层：基础（很少变更）** 31 | - 项目范围标准、架构决策、技术栈 32 | - 每个 AI 会话自动加载 33 | - 提供一致基线，无冗余 34 | - 使用 CLAUDE.md 作为主上下文文件 35 | 36 | **第2层：组件（偶尔变更）** 37 | - 组件边界、架构模式、集成点 38 | - 仅在特定组件内工作时加载 39 | - 将架构决策与实现细节隔离 40 | - 在组件根部使用 CONTEXT.md 文件 41 | 42 | **第3层：功能（频繁变更）** 43 | - 实现细节、技术详情、本地模式 44 | - 与代码共同定位以便立即更新 45 | - 代码更改时最小化文档级联 46 | - 在功能目录内使用 CONTEXT.md 文件 47 | 48 | ## 相比传统系统的优势 49 | 50 | ### 1. 智能上下文加载 51 | 52 | **传统**：AI 加载整个文档语料库，无论任务如何 53 | **三层**：命令仅基于复杂性加载相关层 54 | 55 | 示例： 56 | - 简单查询 → 仅第1层（最少令牌） 57 | - 组件工作 → 第1层 + 相关第2层 58 | - 深度实现 → 所有相关层 59 | 60 | ### 2. 维护效率 61 | 62 | **传统**：每个更改需要更新多个文档 63 | **三层**：更新隔离到适当层 64 | 65 | 示例： 66 | - API 端点更改 → 仅更新第3层 API 文档 67 | - 新组件 → 添加第2层文档，第1层不变 68 | - 编码标准 → 仅更新第1层，适用于所有地方 69 | 70 | ### 3. AI 性能优化 71 | 72 | **传统**：AI 难以找到相关信息 73 | **三层**：结构化层次引导 AI 到精确上下文 74 | 75 | 系统提供： 76 | - 智能体导航的清晰路由逻辑 77 | - 可预测的文档位置 78 | - 通过目标加载实现高效令牌使用 79 | 80 | ## 与套件组件集成 81 | 82 | ### 命令集成 83 | 84 | 命令利用三层结构进行智能操作： 85 | 86 | ``` 87 | 命令执行 → 分析任务复杂性 → 加载适当层 88 | ↓ 89 | 简单：仅第1层 90 | 组件：第1-2层 91 | 复杂：所有相关层 92 | ``` 93 | 94 | ### MCP 服务器集成 95 | 96 | 外部 AI 服务通过层系统接收正确上下文： 97 | 98 | - **Gemini 咨询** - 自动附加 `project-structure.md`（第1层） 99 | - **Context7 查找** - 在已建立的项目上下文内发生 100 | - **推荐** - 与文档架构对齐 101 | 102 | ### 多智能体路由 103 | 104 | 文档结构决定智能体行为： 105 | 106 | - 基于涉及层数生成的智能体数量 107 | - 每个智能体接收目标文档子集 108 | - 无上下文重叠的并行分析 109 | 110 | ## 关键文件及其作用 111 | 112 | ### 基础文件 (ai-context/) 113 | 114 | **docs-overview.md** 115 | - 实现三层文档的模板 116 | - 为 AI 导航映射文档结构 117 | - [查看模板](ai-context/docs-overview.md) 118 | 119 | **project-structure.md** 120 | - 完整技术栈和文件组织 121 | - 所有 AI 智能体的必读文件 122 | - 自动附加到 Gemini 咨询 123 | - [查看模板](ai-context/project-structure.md) 124 | 125 | **system-integration.md** 126 | - 跨组件通信模式 127 | - 多智能体分析的集成架构 128 | - [查看模板](ai-context/system-integration.md) 129 | 130 | **deployment-infrastructure.md** 131 | - 基础设施模式和约束 132 | - AI 推荐的部署上下文 133 | - [查看模板](ai-context/deployment-infrastructure.md) 134 | 135 | **handoff.md** 136 | - AI 交互间的会话连续性 137 | - 任务状态保持 138 | - [查看模板](ai-context/handoff.md) 139 | 140 | ### 上下文模板 141 | 142 | **CLAUDE.md**（第1层） 143 | - 带编码标准的主 AI 上下文 144 | - 项目范围指令和模式 145 | - [查看模板](CLAUDE.md) 146 | 147 | **CONTEXT-tier2-component.md** 148 | - 组件级架构上下文 149 | - [查看模板](CONTEXT-tier2-component.md) 150 | 151 | **CONTEXT-tier3-feature.md** 152 | - 功能特定实现细节 153 | - [查看模板](CONTEXT-tier3-feature.md) 154 | 155 | ## 实施策略 156 | 157 | ### 1. 从模板开始 158 | 159 | 使用提供的模板作为基础： 160 | - 为你的项目复制和自定义 161 | - 保持一致结构 162 | - 专注于 AI 可消费格式 163 | 164 | ### 2. 遵循自然边界 165 | 166 | 让你的架构指导层放置： 167 | - 稳定决策 → 第1层 168 | - 组件设计 → 第2层 169 | - 实现细节 → 第3层 170 | 171 | ### 3. 共同定位文档 172 | 173 | 将 CONTEXT.md 文件与相关代码放在一起： 174 | ``` 175 | backend/ 176 | ├── CONTEXT.md # 后端架构（第2层） 177 | └── src/ 178 | └── api/ 179 | └── CONTEXT.md # API 实现（第3层） 180 | ``` 181 | 182 | ### 4. 维护层次 183 | 184 | 确保清晰关系： 185 | - 第3层引用第2层模式 186 | - 第2层遵循第1层标准 187 | - 无循环依赖 188 | 189 | ### 5. 使用文档命令 190 | 191 | 套件提供管理文档的命令： 192 | - **`/create-docs`** - 为没有现有文档的项目生成初始文档结构 193 | - **`/update-docs`** - 代码更改后重新生成和更新文档以保持一切最新 194 | 195 | ## 衡量成功 196 | 197 | 三层系统成功的标准： 198 | 199 | 1. **AI 智能体快速找到上下文** - 无需搜索无关文档 200 | 2. **更新保持本地化** - 更改不会不必要地级联 201 | 3. **文档保持最新** - 共同定位确保更新发生 202 | 4. **命令高效工作** - 适当上下文自动加载 203 | 5. **MCP 服务器提供相关建议** - 外部 AI 理解你的项目 204 | 205 | --- 206 | 207 | *Claude Code 开发套件的一部分 - 查看[主文档](../README.md)了解完整系统概述。* -------------------------------------------------------------------------------- /templates/docs/ai-context/deployment-infrastructure.md: -------------------------------------------------------------------------------- 1 | # 部署基础设施文档 2 | 3 | *此文档定义基础设施模式、部署策略和运维约束，为 AI 推荐和基础设施决策提供上下文。* 4 | 5 | ## 基础设施架构概述 6 | 7 | ### 部署环境策略 8 | **开发环境**: 9 | - **用途**: [本地开发和功能测试] 10 | - **配置**: [轻量级配置，快速启动] 11 | - **数据**: [模拟数据和测试夹具] 12 | - **监控**: [基本日志记录和调试工具] 13 | 14 | **测试环境**: 15 | - **用途**: [集成测试和 QA 验证] 16 | - **配置**: [生产环境的简化版本] 17 | - **数据**: [匿名化的生产数据子集] 18 | - **监控**: [完整的监控栈和性能测试] 19 | 20 | **生产环境**: 21 | - **用途**: [实际用户流量处理] 22 | - **配置**: [高可用性和性能优化配置] 23 | - **数据**: [完整的业务数据和备份] 24 | - **监控**: [全面监控、告警和事故响应] 25 | 26 | ### 云服务架构 27 | **计算资源**: 28 | - **[云提供商]**: [AWS/Azure/GCP 等主要云服务商] 29 | - **实例类型**: [CPU、内存和存储优化实例选择] 30 | - **自动扩展**: [水平和垂直扩展策略] 31 | - **成本优化**: [预留实例、Spot 实例使用策略] 32 | 33 | **网络架构**: 34 | - **VPC 设计**: [网络隔离和安全组配置] 35 | - **负载均衡**: [应用负载均衡器配置] 36 | - **CDN 策略**: [全球内容分发和缓存策略] 37 | - **DNS 管理**: [域名解析和故障转移配置] 38 | 39 | ## 容器化和编排 40 | 41 | ### 容器策略 42 | **Docker 配置**: 43 | ```dockerfile 44 | # 基础镜像选择策略 45 | FROM [base-image]:[tag] 46 | # 多阶段构建优化 47 | # 安全扫描和漏洞管理 48 | ``` 49 | 50 | **镜像管理**: 51 | - **注册表**: [私有容器注册表策略] 52 | - **版本控制**: [语义化版本和标签策略] 53 | - **安全扫描**: [镜像漏洞扫描和合规性检查] 54 | - **生命周期**: [镜像清理和存储优化] 55 | 56 | ### Kubernetes 部署 57 | **集群架构**: 58 | - **控制平面**: [高可用性控制平面配置] 59 | - **工作节点**: [节点池和资源分配策略] 60 | - **网络**: [CNI 选择和网络策略] 61 | - **存储**: [持久化存储和数据管理] 62 | 63 | **应用部署模式**: 64 | ```yaml 65 | # Deployment 配置策略 66 | apiVersion: apps/v1 67 | kind: Deployment 68 | metadata: 69 | name: [app-name] 70 | spec: 71 | replicas: [replica-count] 72 | strategy: 73 | type: RollingUpdate 74 | rollingUpdate: 75 | maxSurge: [surge-config] 76 | maxUnavailable: [unavailable-config] 77 | ``` 78 | 79 | ## CI/CD 管道 80 | 81 | ### 持续集成策略 82 | **代码质量门禁**: 83 | - **静态代码分析**: [SonarQube/CodeClimate 集成] 84 | - **单元测试**: [测试覆盖率要求和质量指标] 85 | - **安全扫描**: [依赖漏洞扫描和 SAST 工具] 86 | - **构建优化**: [并行构建和缓存策略] 87 | 88 | **自动化测试**: 89 | - **单元测试**: [快速反馈和高覆盖率] 90 | - **集成测试**: [服务间集成验证] 91 | - **端到端测试**: [用户流程验证] 92 | - **性能测试**: [负载测试和性能基准] 93 | 94 | ### 持续部署策略 95 | **部署模式**: 96 | - **蓝绿部署**: [零停机部署和快速回滚] 97 | - **滚动更新**: [渐进式部署和风险控制] 98 | - **金丝雀发布**: [小流量验证和渐进式推广] 99 | - **功能开关**: [运行时功能控制和 A/B 测试] 100 | 101 | **环境推进**: 102 | ``` 103 | 开发环境 → 测试环境 → 预生产环境 → 生产环境 104 | ↓ ↓ ↓ ↓ 105 | [自动触发] [人工审批] [自动化测试] [监控验证] 106 | ``` 107 | 108 | ## 监控和可观测性 109 | 110 | ### 监控栈架构 111 | **指标收集**: 112 | - **应用指标**: [业务指标和性能指标] 113 | - **基础设施指标**: [CPU、内存、网络、存储] 114 | - **自定义指标**: [领域特定的业务指标] 115 | - **SLA 指标**: [可用性、响应时间、错误率] 116 | 117 | **日志管理**: 118 | - **结构化日志**: [JSON 格式和标准化字段] 119 | - **日志聚合**: [ELK/EFK 栈或云原生解决方案] 120 | - **日志保留**: [数据保留策略和成本优化] 121 | - **查询和分析**: [日志搜索和可视化] 122 | 123 | ### 告警和事故响应 124 | **告警策略**: 125 | - **分级告警**: [严重程度分类和响应时间] 126 | - **告警路由**: [基于服务和团队的告警分发] 127 | - **告警抑制**: [相关告警合并和噪音减少] 128 | - **升级策略**: [自动升级和值班轮换] 129 | 130 | **事故管理**: 131 | - **事故等级**: [P0-P4 事故分类和响应流程] 132 | - **战情室**: [事故响应协调和沟通] 133 | - **事后分析**: [无责事后复盘和改进措施] 134 | - **知识管理**: [故障手册和解决方案知识库] 135 | 136 | ## 安全和合规 137 | 138 | ### 基础设施安全 139 | **网络安全**: 140 | - **防火墙**: [网络访问控制和安全组] 141 | - **VPN 接入**: [安全远程访问] 142 | - **网络隔离**: [微分段和零信任架构] 143 | - **DDoS 防护**: [攻击检测和缓解] 144 | 145 | **数据保护**: 146 | - **加密**: [传输和静态数据加密] 147 | - **密钥管理**: [密钥轮换和安全存储] 148 | - **数据备份**: [定期备份和恢复测试] 149 | - **数据分类**: [敏感数据识别和保护] 150 | 151 | ### 合规性要求 152 | **法规合规**: 153 | - **[GDPR/CCPA]**: [数据隐私保护措施] 154 | - **[SOC 2/ISO 27001]**: [安全控制和审计要求] 155 | - **[PCI DSS]**: [支付数据处理安全要求] 156 | - **[HIPAA]**: [医疗数据保护要求（如适用）] 157 | 158 | **审计和治理**: 159 | - **访问审计**: [权限审查和访问日志] 160 | - **变更管理**: [基础设施变更审批流程] 161 | - **配置管理**: [基础设施即代码和版本控制] 162 | - **风险评估**: [定期安全风险评估和缓解] 163 | 164 | ## 成本优化策略 165 | 166 | ### 资源优化 167 | **计算资源**: 168 | - **实例规格**: [CPU 和内存使用率优化] 169 | - **自动扩展**: [需求驱动的资源分配] 170 | - **预留实例**: [长期使用的成本节约] 171 | - **Spot 实例**: [批处理任务的成本优化] 172 | 173 | **存储优化**: 174 | - **存储分层**: [热、温、冷数据存储策略] 175 | - **数据生命周期**: [自动数据归档和删除] 176 | - **压缩和去重**: [存储空间优化] 177 | - **备份策略**: [备份成本和恢复时间平衡] 178 | 179 | ### 成本监控 180 | **预算控制**: 181 | - **成本分配**: [按服务和团队的成本分摊] 182 | - **预算告警**: [成本超标预警和控制] 183 | - **使用分析**: [资源使用效率分析] 184 | - **优化建议**: [定期成本优化评审] 185 | 186 | --- 187 | 188 | *此部署基础设施文档为基础设施决策和运维实践提供上下文。随着技术和业务需求变化定期更新。* -------------------------------------------------------------------------------- /templates/docs/ai-context/docs-overview.md: -------------------------------------------------------------------------------- 1 | # 文档架构 2 | 3 | 此项目使用**三层文档系统**，按稳定性和范围组织知识，实现高效的 AI 上下文加载和可扩展开发。 4 | 5 | ## 三层系统工作原理 6 | 7 | **第1层（基础）**：稳定的、系统范围的文档，很少变更 - 架构原则、技术决策、跨组件模式和核心开发协议。 8 | 9 | **第2层（组件）**：主要组件的架构章程 - 高层设计原则、集成模式和组件范围约定，不包含功能特定细节。 10 | 11 | **第3层（功能特定）**：与代码共同定位的详细文档 - 具体实现模式、技术细节和随功能演进的局部架构决策。 12 | 13 | 此层次结构允许 AI 智能体高效加载目标上下文，同时维护稳定的核心知识基础。 14 | 15 | ## 文档原则 16 | - **共同定位**：文档与相关代码放在一起 17 | - **智能扩展**：在必要时自动创建新文档文件 18 | - **AI 优先**：为高效 AI 上下文加载和机器可读模式优化 19 | 20 | ## 第1层：基础文档（系统范围） 21 | 22 | - **[主上下文](/CLAUDE.md)** - *每个会话必需。* 编码标准、安全要求、MCP 服务器集成模式和开发协议 23 | - **[项目结构](/docs/ai-context/project-structure.md)** - *必读。* 完整技术栈、文件树和系统架构。必须附加到 Gemini 咨询 24 | - **[系统集成](/docs/ai-context/system-integration.md)** - *跨组件工作用。* 通信模式、数据流、测试策略和性能优化 25 | - **[部署基础设施](/docs/ai-context/deployment-infrastructure.md)** - *基础设施模式。* 容器化、监控、CI/CD 工作流和扩展策略 26 | - **[任务管理](/docs/ai-context/handoff.md)** - *会话连续性。* 当前任务、文档系统进度和下次会话目标 27 | 28 | ## 第2层：组件级文档 29 | 30 | ### 后端组件 31 | - **[后端上下文](/backend/CONTEXT.md)** - *服务器实现。* API 模式、数据库集成、服务架构和性能考虑 32 | - **[工作服务](/workers/CONTEXT.md)** - *后台处理。* 作业队列模式、调度和异步任务管理 33 | - **[共享库](/shared/CONTEXT.md)** - *可重用代码。* 通用工具、共享类型和跨组件功能 34 | 35 | ### 前端组件 36 | - **[Web 应用](/frontend/CONTEXT.md)** - *客户端实现。* UI 模式、状态管理、路由和用户交互模式 37 | - **[移动应用](/mobile/CONTEXT.md)** - *移动实现。* 平台特定模式、原生集成和移动优化 38 | - **[管理仪表板](/admin/CONTEXT.md)** - *管理界面。* 权限模式、管理工作流和管理工具 39 | 40 | ### 基础设施组件 41 | - **[基础设施代码](/infrastructure/CONTEXT.md)** - *IaC 模式。* Terraform/CloudFormation 模板、资源定义和部署自动化 42 | - **[监控设置](/monitoring/CONTEXT.md)** - *可观测性模式。* 指标收集、告警规则和仪表板配置 43 | 44 | ## 第3层：功能特定文档 45 | 46 | 与代码共同定位的详细 CONTEXT.md 文件，最小级联效应： 47 | 48 | ### 后端功能文档 49 | - **[核心服务](/backend/src/core/services/CONTEXT.md)** - *业务逻辑模式。* 服务架构、数据处理、集成模式和错误处理 50 | - **[API 层](/backend/src/api/CONTEXT.md)** - *API 模式。* 端点设计、验证、中间件和请求/响应处理 51 | - **[数据库集成](/backend/src/database/CONTEXT.md)** - *数据模式。* ORM 模式、查询优化、迁移策略和数据建模 52 | - **[外部集成](/backend/src/integrations/CONTEXT.md)** - *服务集成。* 第三方 API、webhook 处理和外部服务模式 53 | 54 | ### 前端功能文档 55 | - **[用户界面组件](/frontend/src/components/CONTEXT.md)** - *UI 模式。* 组件架构、样式管理、可访问性和用户体验模式 56 | - **[状态管理](/frontend/src/store/CONTEXT.md)** - *应用状态。* 状态架构、数据流、缓存策略和状态同步 57 | - **[路由和导航](/frontend/src/router/CONTEXT.md)** - *导航模式。* 路由配置、守卫、懒加载和导航流程 58 | 59 | ## 使用指南 60 | 61 | ### 对于 AI 智能体 62 | 63 | **简单任务**：仅加载第1层文档 64 | ``` 65 | - CLAUDE.md（编码标准） 66 | - project-structure.md（项目概述） 67 | ``` 68 | 69 | **组件工作**：加载第1层 + 相关第2层 70 | ``` 71 | - 基础文档 + 特定组件 CONTEXT.md 72 | ``` 73 | 74 | **复杂实现**：加载所有相关层 75 | ``` 76 | - 基础 + 组件 + 功能特定文档 77 | ``` 78 | 79 | ### 对于开发者 80 | 81 | **添加新功能**： 82 | 1. 检查现有第3层文档是否适用 83 | 2. 必要时创建新的 CONTEXT.md 84 | 3. 更新相关第2层文档（如有架构变更） 85 | 4. 第1层文档保持不变 86 | 87 | **新组件**： 88 | 1. 创建组件级 CONTEXT.md（第2层） 89 | 2. 为主要功能创建第3层文档 90 | 3. 更新 docs-overview.md 添加导航 91 | 92 | ## 文档模板 93 | 94 | 使用标准化模板确保一致性： 95 | 96 | - **[第1层模板](templates/CLAUDE.md)** - 主项目上下文 97 | - **[第2层模板](templates/CONTEXT-tier2-component.md)** - 组件架构 98 | - **[第3层模板](templates/CONTEXT-tier3-feature.md)** - 功能实现 99 | 100 | ## 文档维护 101 | 102 | ### 自动化 103 | - 文档与代码变更同步检查 104 | - 过期文档检测和警告 105 | - 模板一致性验证 106 | 107 | ### 手动审核 108 | - 季度文档架构审核 109 | - 新团队成员文档可用性测试 110 | - AI 上下文加载效率分析 111 | 112 | --- 113 | 114 | *此文档架构是 Claude Code 开发套件的核心。它确保 AI 智能体始终具备适当上下文，同时保持文档的可维护性和相关性。* -------------------------------------------------------------------------------- /templates/docs/ai-context/handoff.md: -------------------------------------------------------------------------------- 1 | # 任务交接文档 2 | 3 | *此文档帮助在 Claude Code 会话之间维护上下文连续性和任务状态。* 4 | 5 | ## 当前会话状态 6 | 7 | ### 主要目标 8 | [描述当前会话的主要目标或项目重点] 9 | 10 | ### 已完成任务 11 | - [x] [已完成的任务1] - [简要说明和结果] 12 | - [x] [已完成的任务2] - [关键成果和影响] 13 | - [x] [已完成的任务3] - [实现细节和文档位置] 14 | 15 | ### 正在进行的任务 16 | - [ ] [进行中的任务1] - [当前状态和下一步] 17 | - [ ] [进行中的任务2] - [遇到的挑战和解决方向] 18 | - [ ] [进行中的任务3] - [依赖关系和时间线] 19 | 20 | ### 待办任务 21 | - [ ] [待办任务1] - [优先级和预期工作量] 22 | - [ ] [待办任务2] - [前置条件和资源需求] 23 | - [ ] [待办任务3] - [相关文档和参考资料] 24 | 25 | ## 技术上下文 26 | 27 | ### 当前技术状态 28 | **架构决策**: [最近的重要架构决策] 29 | **性能状态**: [当前性能指标和优化需求] 30 | **集成状态**: [外部服务集成状态] 31 | **测试覆盖**: [测试状态和质量指标] 32 | 33 | ### 关键发现和洞察 34 | - **[技术洞察1]**: [发现的问题和建议解决方案] 35 | - **[架构洞察2]**: [系统设计改进机会] 36 | - **[性能洞察3]**: [优化建议和预期收益] 37 | 38 | ### 需要关注的技术债务 39 | 1. **[技术债务1]** - [影响和紧急程度] - [建议解决时间线] 40 | 2. **[技术债务2]** - [风险评估] - [缓解措施] 41 | 3. **[技术债务3]** - [重构建议] - [资源需求] 42 | 43 | ## 文档系统状态 44 | 45 | ### 文档完整性 46 | - **第1层文档**: [基础文档状态 - 完整/需更新/缺失] 47 | - **第2层文档**: [组件文档覆盖率和质量] 48 | - **第3层文档**: [功能文档的同步状态] 49 | 50 | ### 文档更新需求 51 | - [ ] [需要更新的文档1] - [更新原因和优先级] 52 | - [ ] [需要创建的文档2] - [缺失的上下文和影响] 53 | - [ ] [需要重构的文档3] - [当前问题和改进方向] 54 | 55 | ## 决策记录 56 | 57 | ### 最近的重要决策 58 | **[决策日期]**: [决策标题] 59 | - **背景**: [导致决策的情况] 60 | - **选择**: [做出的决策和理由] 61 | - **影响**: [对项目的影响和后续行动] 62 | - **状态**: [实施状态和验证结果] 63 | 64 | ### 待决策问题 65 | 1. **[待决策问题1]** - [问题描述和选项分析] 66 | 2. **[待决策问题2]** - [利益相关者和决策时间线] 67 | 3. **[待决策问题3]** - [风险评估和建议方向] 68 | 69 | ## 下次会话建议 70 | 71 | ### 优先事项 72 | 1. **[高优先级任务]** - [为什么重要和预期结果] 73 | 2. **[中优先级任务]** - [依赖关系和资源需求] 74 | 3. **[低优先级任务]** - [时间线和质量要求] 75 | 76 | ### 上下文提醒 77 | - **关键文件**: [下次会话应该首先查看的文件] 78 | - **重要约束**: [需要记住的技术或业务约束] 79 | - **相关联系人**: [可能需要咨询的团队成员或专家] 80 | 81 | ### 预期挑战 82 | - **[技术挑战]** - [预期困难和准备建议] 83 | - **[资源挑战]** - [时间或人力资源限制] 84 | - **[集成挑战]** - [与其他系统或团队的协调需求] 85 | 86 | ## 资源和参考 87 | 88 | ### 关键文档链接 89 | - [重要文档1] - [为什么重要和使用场景] 90 | - [参考资料2] - [相关技术文档或标准] 91 | - [决策记录3] - [历史决策和当前相关性] 92 | 93 | ### 外部资源 94 | - [API文档] - [第三方服务文档] 95 | - [技术规范] - [行业标准或最佳实践] 96 | - [社区资源] - [有用的开源项目或讨论] 97 | 98 | ### 团队联系信息 99 | - **[角色1]**: [联系方式] - [负责领域和可用时间] 100 | - **[角色2]**: [联系方式] - [专业领域和协作方式] 101 | 102 | --- 103 | 104 | *定期更新此文档以确保会话间的连续性和效率。每次主要任务完成或会话结束时都应更新相关部分。* -------------------------------------------------------------------------------- /templates/docs/ai-context/project-structure.md: -------------------------------------------------------------------------------- 1 | # 项目结构模板 2 | 3 | 本文档提供了一个完整技术栈和文件树结构的文档模板。**AI 智能体必须先阅读此文件以了解项目组织，然后再进行任何更改。** 4 | 5 | ## 技术栈模板 6 | 7 | ### 后端技术 8 | 记录你的后端技术选择： 9 | - **[语言] [版本]** 与 **[包管理器]** - 依赖管理和打包 10 | - **[Web框架] [版本]** - 带特定功能的 Web 框架（异步、类型提示等） 11 | - **[服务器] [版本]** - 应用服务器配置 12 | - **[配置] [版本]** - 配置管理方法 13 | 14 | 示例： 15 | ``` 16 | - Python 3.11+ 与 Poetry - 依赖管理和打包 17 | - FastAPI 0.115.0+ - 带类型提示和异步支持的 Web 框架 18 | - Uvicorn 0.32.0+ - 带标准扩展的 ASGI 服务器 19 | - Pydantic Settings 2.5.2+ - 带类型验证的配置管理 20 | ``` 21 | 22 | ### 集成服务与 API 23 | 记录外部服务和集成： 24 | - **[服务名] [API/SDK版本]** - 用途和使用模式 25 | - **[AI服务] [版本]** - AI/ML 服务集成详情 26 | - **[数据库] [版本]** - 数据存储和管理 27 | - **[监控] [版本]** - 可观测性和日志 28 | 29 | ### 实时通信 30 | 记录实时功能： 31 | - **[WebSocket库]** - 实时通信模式 32 | - **[HTTP客户端]** - 异步 HTTP 通信 33 | - **[消息队列]** - 事件处理（如适用） 34 | 35 | ### 开发与质量工具 36 | 记录开发工具链： 37 | - **[格式化器] [版本]** - 代码格式化 38 | - **[代码检查器] [版本]** - 代码质量和代码检查 39 | - **[类型检查器] [版本]** - 静态类型检查 40 | - **[测试框架] [版本]** - 测试方法 41 | - **[任务运行器]** - 构建自动化和任务编排 42 | 43 | ### 前端技术（如适用） 44 | 记录前端技术栈： 45 | - **[语言] [版本]** - 前端开发语言 46 | - **[框架] [版本]** - UI 框架 47 | - **[构建工具] [版本]** - 开发和构建工具 48 | - **[部署] [版本]** - 部署和托管方法 49 | 50 | ### 未来技术 51 | 记录计划的技术添加： 52 | - **[计划技术]** - 未来集成计划 53 | - **[平台]** - 目标平台扩展 54 | - **[服务]** - 计划的服务集成 55 | 56 | ## 完整项目结构模板 57 | 58 | ``` 59 | [项目名称]/ 60 | ├── README.md # 项目概览和设置 61 | ├── CLAUDE.md # 主 AI 上下文文件 62 | ├── [构建文件] # 构建配置（Makefile、package.json 等） 63 | ├── .gitignore # Git 忽略模式 64 | ├── .[IDE配置]/ # IDE 工作区配置 65 | │ ├── settings.[ext] # IDE 设置 66 | │ ├── extensions.[ext] # 推荐扩展 67 | │ └── launch.[ext] # 调试配置 68 | ├── [后端目录]/ # 后端应用 69 | │ ├── CONTEXT.md # 后端特定 AI 上下文 70 | │ ├── src/ # 源代码 71 | │ │ ├── config/ # 配置管理 72 | │ │ │ └── settings.[ext] # 应用设置 73 | │ │ ├── core/ # 核心业务逻辑 74 | │ │ │ ├── CONTEXT.md # 核心逻辑模式 75 | │ │ │ ├── services/ # 业务服务 76 | │ │ │ │ ├── [service1].[ext] # 服务实现 77 | │ │ │ │ └── [service2].[ext] 78 | │ │ │ ├── models/ # 数据模型 79 | │ │ │ │ ├── [model1].[ext] # 模型定义 80 | │ │ │ │ └── [model2].[ext] 81 | │ │ │ └── utils/ # 工具函数 82 | │ │ │ ├── logging.[ext] # 结构化日志 83 | │ │ │ ├── validation.[ext] # 输入验证 84 | │ │ │ └── helpers.[ext] # 辅助函数 85 | │ │ ├── api/ # API 层 86 | │ │ │ ├── CONTEXT.md # API 模式和约定 87 | │ │ │ ├── routes/ # API 路由定义 88 | │ │ │ │ ├── [resource1].[ext] # 资源特定路由 89 | │ │ │ │ └── [resource2].[ext] 90 | │ │ │ ├── middleware/ # API 中间件 91 | │ │ │ │ ├── auth.[ext] # 认证中间件 92 | │ │ │ │ ├── logging.[ext] # 请求日志 93 | │ │ │ │ └── validation.[ext] # 请求验证 94 | │ │ │ └── schemas/ # 请求/响应模式 95 | │ │ │ ├── [schema1].[ext] # 数据模式 96 | │ │ │ └── [schema2].[ext] 97 | │ │ └── integrations/ # 外部服务集成 98 | │ │ ├── CONTEXT.md # 集成模式 99 | │ │ ├── [service1]/ # 服务特定集成 100 | │ │ │ ├── client.[ext] # API 客户端 101 | │ │ │ ├── models.[ext] # 集成模型 102 | │ │ │ └── handlers.[ext] # 响应处理器 103 | │ │ └── [service2]/ 104 | │ ├── tests/ # 测试套件 105 | │ │ ├── unit/ # 单元测试 106 | │ │ ├── integration/ # 集成测试 107 | │ │ └── fixtures/ # 测试夹具和数据 108 | │ ├── [包文件] # 包配置 109 | │ └── [环境文件] # 环境配置 110 | ├── [前端目录]/ # 前端应用（如适用） 111 | │ ├── CONTEXT.md # 前端特定 AI 上下文 112 | │ ├── src/ # 源代码 113 | │ │ ├── components/ # UI 组件 114 | │ │ │ ├── CONTEXT.md # 组件模式 115 | │ │ │ ├── common/ # 共享组件 116 | │ │ │ └── [feature]/ # 功能特定组件 117 | │ │ ├── pages/ # 页面组件/路由 118 | │ │ │ ├── [page1].[ext] # 页面实现 119 | │ │ │ └── [page2].[ext] 120 | │ │ ├── stores/ # 状态管理 121 | │ │ │ ├── CONTEXT.md # 状态管理模式 122 | │ │ │ ├── [store1].[ext] # 存储实现 123 | │ │ │ └── [store2].[ext] 124 | │ │ ├── api/ # API 客户端层 125 | │ │ │ ├── CONTEXT.md # 客户端模式 126 | │ │ │ ├── client.[ext] # HTTP 客户端设置 127 | │ │ │ └── endpoints/ # API 端点定义 128 | │ │ ├── utils/ # 工具函数 129 | │ │ │ ├── logging.[ext] # 客户端日志 130 | │ │ │ ├── validation.[ext] # 表单验证 131 | │ │ │ └── helpers.[ext] # 辅助函数 132 | │ │ └── assets/ # 静态资源 133 | │ ├── tests/ # 前端测试 134 | │ ├── [构建配置] # 构建配置 135 | │ └── [包文件] # 包配置 136 | ├── docs/ # 文档 137 | │ ├── ai-context/ # AI特定文档 138 | │ │ ├── project-structure.md # 此文件 139 | │ │ ├── docs-overview.md # 文档架构 140 | │ │ ├── system-integration.md # 集成模式 141 | │ │ ├── deployment-infrastructure.md # 基础设施文档 142 | │ │ └── handoff.md # 任务管理 143 | │ ├── api/ # API 文档 144 | │ ├── deployment/ # 部署指南 145 | │ └── development/ # 开发指南 146 | ├── scripts/ # 自动化脚本 147 | │ ├── setup.[ext] # 环境设置 148 | │ ├── deploy.[ext] # 部署脚本 149 | │ └── maintenance/ # 维护脚本 150 | ├── [基础设施目录]/ # 基础设施即代码（如适用） 151 | │ ├── [提供商]/ # 云提供商配置 152 | │ ├── docker/ # 容器配置 153 | │ └── monitoring/ # 监控和告警 154 | └── [配置文件] # 根级配置文件 155 | ``` 156 | 157 | --- 158 | 159 | *此模板为项目结构文档提供了全面基础。根据你的特定技术栈、架构决策和组织要求进行调整。* -------------------------------------------------------------------------------- /templates/docs/ai-context/system-integration.md: -------------------------------------------------------------------------------- 1 | # 系统集成架构 2 | 3 | *此文档定义跨组件通信模式、数据流和集成策略，为多智能体分析和系统级决策提供上下文。* 4 | 5 | ## 集成架构概述 6 | 7 | ### 系统边界定义 8 | **核心系统**: [定义核心应用边界和职责] 9 | **外部集成**: [第三方系统和服务边界] 10 | **数据边界**: [数据所有权和访问模式] 11 | **安全边界**: [认证和授权边界定义] 12 | 13 | ### 通信协议标准 14 | - **内部通信**: [组件间通信协议 - REST、gRPC、消息队列等] 15 | - **外部 API**: [与外部服务的通信标准] 16 | - **实时通信**: [WebSocket、SSE 或其他实时协议] 17 | - **异步处理**: [后台任务和事件处理模式] 18 | 19 | ## 数据流架构 20 | 21 | ### 主要数据流向 22 | ``` 23 | [用户请求] → [API 网关] → [业务服务] → [数据存储] 24 | ↓ 25 | [外部服务] ← [集成层] ← [事件处理] ← [业务逻辑] 26 | ``` 27 | 28 | ### 数据一致性策略 29 | - **ACID 事务**: [需要强一致性的业务场景] 30 | - **最终一致性**: [可接受延迟一致性的场景] 31 | - **补偿模式**: [分布式事务的补偿机制] 32 | - **数据同步**: [跨系统数据同步策略] 33 | 34 | ### 缓存策略 35 | - **应用缓存**: [内存缓存策略和失效机制] 36 | - **分布式缓存**: [Redis/Memcached 使用模式] 37 | - **CDN 缓存**: [静态资源和 API 响应缓存] 38 | - **数据库缓存**: [查询结果缓存优化] 39 | 40 | ## 服务集成模式 41 | 42 | ### API 集成模式 43 | **RESTful API 设计**: 44 | - 统一的 URL 结构：`/api/v1/{resource}/{id}/{action}` 45 | - 标准 HTTP 动词使用 46 | - 一致的响应格式：`{data: {}, error: null, meta: {}}` 47 | - 适当的 HTTP 状态码 48 | 49 | **认证和授权**: 50 | - API 密钥管理 51 | - JWT 令牌验证 52 | - OAuth 2.0 流程 53 | - 权限级别定义 54 | 55 | ### 消息队列集成 56 | - **异步任务处理**: [后台任务队列模式] 57 | - **事件驱动架构**: [领域事件发布和订阅] 58 | - **可靠消息传递**: [消息确认和重试机制] 59 | - **消息路由**: [基于内容的消息路由] 60 | 61 | ### 数据库集成策略 62 | - **主从复制**: [读写分离和数据同步] 63 | - **分片策略**: [水平扩展和数据分布] 64 | - **跨数据库事务**: [分布式事务处理] 65 | - **数据迁移**: [版本升级和数据迁移策略] 66 | 67 | ## 外部服务集成 68 | 69 | ### 第三方 API 集成 70 | **[服务A] 集成**: 71 | - **认证方式**: [API 密钥、OAuth 等] 72 | - **速率限制**: [请求频率限制和处理] 73 | - **错误处理**: [API 错误响应处理策略] 74 | - **数据映射**: [外部数据到内部模型的转换] 75 | 76 | **[服务B] 集成**: 77 | - **Webhook 处理**: [入站 Webhook 验证和处理] 78 | - **批量操作**: [大量数据的批处理策略] 79 | - **同步策略**: [数据同步频率和冲突解决] 80 | - **降级处理**: [服务不可用时的降级策略] 81 | 82 | ### 监控和可观测性 83 | - **链路追踪**: [分布式请求追踪] 84 | - **指标收集**: [关键性能指标定义] 85 | - **日志聚合**: [结构化日志和分析] 86 | - **健康检查**: [服务健康状态监控] 87 | 88 | ## 性能优化策略 89 | 90 | ### 网络优化 91 | - **连接池管理**: [HTTP 连接复用和池管理] 92 | - **请求合并**: [批量请求减少网络往返] 93 | - **压缩策略**: [响应数据压缩] 94 | - **CDN 策略**: [全球内容分发优化] 95 | 96 | ### 并发处理 97 | - **异步处理**: [非阻塞 I/O 和异步编程] 98 | - **线程池管理**: [并发任务执行优化] 99 | - **背压控制**: [系统负载控制和流量整形] 100 | - **断路器模式**: [故障隔离和快速失败] 101 | 102 | ### 资源管理 103 | - **内存优化**: [对象生命周期管理] 104 | - **数据库连接**: [连接池配置和优化] 105 | - **文件句柄**: [资源清理和限制管理] 106 | - **CPU 使用**: [计算密集任务优化] 107 | 108 | ## 错误处理和恢复 109 | 110 | ### 错误分类和处理 111 | - **暂时性错误**: [网络超时、服务临时不可用] 112 | - **永久性错误**: [配置错误、权限不足] 113 | - **业务错误**: [数据验证失败、业务规则违反] 114 | - **系统错误**: [内存不足、磁盘空间不够] 115 | 116 | ### 恢复策略 117 | - **重试机制**: [指数退避和最大重试次数] 118 | - **降级服务**: [核心功能保证和非核心功能降级] 119 | - **熔断器**: [故障快速检测和隔离] 120 | - **补偿操作**: [事务回滚和数据一致性保证] 121 | 122 | ### 灾难恢复 123 | - **数据备份**: [定期备份和恢复测试] 124 | - **服务冗余**: [多可用区部署] 125 | - **故障转移**: [自动故障检测和切换] 126 | - **恢复程序**: [灾难恢复标准操作程序] 127 | 128 | ## 安全集成考虑 129 | 130 | ### 数据保护 131 | - **传输加密**: [HTTPS/TLS 配置] 132 | - **存储加密**: [静态数据加密策略] 133 | - **密钥管理**: [加密密钥轮换和保护] 134 | - **敏感数据处理**: [PII 数据处理和匿名化] 135 | 136 | ### 访问控制 137 | - **身份验证**: [用户身份验证流程] 138 | - **授权控制**: [细粒度权限控制] 139 | - **审计日志**: [安全事件记录和分析] 140 | - **会话管理**: [会话安全和超时处理] 141 | 142 | --- 143 | 144 | *此系统集成文档为跨组件工作和系统级优化提供架构上下文。定期审查和更新以反映系统演进。* --------------------------------------------------------------------------------