内容
# 克劳德代码框架
全面配置框架为克劳德代码命令行界面，具备专业代理、自定义命令、规则和模板。该框架建立在罗德里戈·布拉纳斯和佩德罗·诺克的学习成果之上。
## 🏗️ 框架结构
```
.claude/
├── agents/ # 不同任务的专业人工智能代理
├── commands/ # 自定义斜杠命令
├── config/ # 配置文件
├── rules/ # 开发规则和标准
└── templates/ # 文档模板
```
## 🤖 专业代理
该框架包含适用于不同开发工作流的专用代理：
### 架构与规划
- **软件架构师**：系统设计、干净架构模式、技术解决方案
- **数据库架构师**：数据库设计、Drizzle ORM、模式优化、迁移
- **React 干净架构师**：React 干净架构、状态管理、自定义钩子
### 开发与实施
- **API 标准专家**：API 设计模式、HTTP 标准、Hono 框架
- **React 编码员**：React 19 组件开发、简单优先哲学
- **TypeScript 专家**：TypeScript 指导、类型错误、先进类型功能
- **任务实施协调器**：从计划中协调任务执行
### 质量与测试
- **TDD 测试工程师**：使用 Vitest 进行测试驱动开发、模拟策略
- **技术负责人评审员**：技术领导、代码评审、架构决策
- **设计评审**：UI/UX 合规性、视觉一致性、易用性
- **UX 守护者**：边缘情况发现、用户旅程测试、关键测试路径
### 代码质量与修复
- **TypeScript 诊断修复器**：自动 TypeScript 错误解决
- **Biome lint 修复器**：带有规则意识的自动 Biome lint 修复
### 产品与业务
- **业务分析师**：需求收集、流程建模、用例
- **产品经理 PRD**：PRD 创建、功能规范、成功指标
- **领域专家验证器**：领域逻辑验证、业务规则验证
- **UX/UI 设计师**：UI/UX 设计、线框图、设计系统、易用性
### 工作流与编排
- **Git 工作流**：Git 操作、约定提交、分支策略
- **任务分析器**：用于代币优化的预实施分析
## 📋 斜杠命令
### 功能开发
- `/feature:discovery` - 功能发现和规划过程
- `/feature:prd` - 产品需求文档创建
- `/feature:techspec` - 技术规范生成
- `/feature:tasks` - 任务分解和规划
- `/feature:workflow` - 完整功能开发工作流
### 代码质量与修复
- `/fix:types` - 使用自动诊断修复 TypeScript 错误
- `/fix:lint` - 使用规则感知自动修复进行 Biome linting
- `/fix:tests` - Vitest 失败分析和 TDD 基础修复
### Git 操作
- `/git:commit` - 智能约定提交（仅限功能分支）
- `/git:branch` - 从 dev 创建功能分支
- `/git:push` - 推送更改并创建 PR 到 dev
- `/git:sync` - 与 dev 分支同步本地存储库
### 分析与实施
- `/analyze` - 用于代币优化的预实施分析
- `/implement` - 从计划和规范执行任务
### 设计与测试
- `/design:review` - UI/UX 合规性和可访问性审查
## 📚 规则与标准
### 核心原则
- **干净架构与领域驱动设计**：在它们增加明显价值的地方应用
- **TypeScript-first**：具有有意义类型的严格类型
- **测试驱动开发**：测试优先，实施其次
### 基本设计原则
- **DRY（不要重复自己）**：知识的单一来源
- **YAGNI（你不会需要它）**：仅在实际需要时实施
- **KISS（保持简单，笨蛋）**：简单作为关键设计目标
- **TDA（告诉，不要问）**：告诉对象该怎么做，而不是询问它们的数据
- **SOLID 原则**：单一责任、开放/封闭、里斯科夫替换、接口隔离、依赖倒置
- **对象健美操**：9 条更好的面向对象代码质量规则
### 技术标准
- **运行时**：Bun（从不使用 npm/yarn）- `bun run test`，从不 `bun test`
- **测试**：通过 `bun run test` 使用 Vitest，采取 TDD 方法
- **模式验证**：后端使用 TypeBox，前端使用 Zod
- **数据库**：使用 Drizzle ORM 和 PostgreSQL，表名使用蛇形，TypeScript 使用驼峰
- **ID**：ULID 代替 UUID
- **API**：Hono 用于 HTTP 路由（不是 Express 或 Bun.serve）
- **日志**：使用 Winston 进行结构化 JSON 日志
### 代码质量标准
- **TypeScript 模式**：从不使用 `any`，适当的接口，类型守卫
- **函数设计**：复杂参数使用选项对象，预期错误使用 Result 模式
- **命名约定**：描述性、一致性、可搜索的名称
- **文件夹结构**：具有干净架构层的特性驱动组织
- **基本规则**：全面开发指南，确保代码质量的一致性
## 🔌 MCP（模型上下文协议）服务器
该框架利用多个 MCP 服务器来增强功能：
### 可用 MCP 服务器
| 服务器 | 目的 | 文档 |
| ------------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| **context7** | 库文档和代码示例 | [Context7 MCP](https://context7.com/) |
| **Docker_MCP_Toolkit** | Docker 容器管理 | [Docker MCP](https://www.docker.com/products/mcp-catalog-and-toolkit/) |
| **magic** | UI 组件生成和徽标搜索 | [Magic MCP](https://21st.dev/magic) |
| **perplexity-mcp** | 网络搜索和推理 | [Perplexity MCP](https://www.perplexity.ai/help-center/en/articles/11502712-local-and-remote-mcps-for-perplexity) |
| **playwright** | 浏览器自动化和测试 | [Playwright MCP](https://github.com/microsoft/playwright-mcp) |
| **sequential-thinking** | 逐步问题解决 | [Sequential Thinking MCP](https://github.com/modelcontextprotocol/servers/tree/main/src/sequentialthinking) |
| **zen** | 全面的 AI 工作流 | [Zen MCP](https://github.com/BeehiveInnovations/zen-mcp-server) |
| **serena** | 语义代码分析 | [Serena MCP](https://github.com/oraios/serena) |
| **filesystem-with-morph** | 高级文件操作 | [Filesystem Morph MCP](https://docs.morphllm.com/guides/claude-code) |
### MCP 服务器功能
- **代码分析**：使用 Serena 进行语义理解
- **UI 生成**：使用 Magic 进行组件创建
- **文档**：通过 Context7 进行实时库文档
- **测试**：使用 Playwright 进行浏览器自动化
- **推理**：使用 Sequential Thinking 进行高级问题解决
- **搜索**：使用 Perplexity 进行网络研究
- **基础设施**：Docker 管理工具包
### 配置
要配置这些 MCP 服务器，请在 `~/.claude.json` 文件中添加 `mcpServers` 部分。有关完整配置模板，请参阅 [mcp-config-example.json](mcp-config-example.json)。
**所需 API 密钥：**
- Perplexity：从 [Perplexity API](https://docs.perplexity.ai/docs/getting-started) 获取您的 API 密钥
- Zen：需要 OpenAI、Gemini 和/或 OpenRouter API 密钥
- Morph：从 [Morph](https://morphllm.com/) 获取您的 API 密钥
**无需 API 密钥：**
- Context7、Docker_MCP_Toolkit、Playwright、Sequential-thinking、Serena
## 🚀 入门指南
1. **安装克劳德代码命令行界面**
```bash
npm install -g @anthropic/claude-code
```
2. **克隆此框架**
```bash
git clone <your-repo-url>
cd claude-code-framework
```
3. **将配置复制到全局克劳德目录**
```bash
cp -r .claude/* ~/.claude/
```
4. **在 `~/.claude.json` 中配置 MCP 服务器**（参见 [mcp-config-example.json](mcp-config-example.json) 获取配置模板）
5. **开始使用专业代理和命令**
```bash
claude /agent:list
claude /feature:discovery "new user authentication"
```
## 🎓 鸣谢与启发
该框架建立在罗德里戈·布拉纳斯和佩德罗·诺克分享的学习成果和最佳实践之上。
- **[罗德里戈·布拉纳斯](https://branas.io/)** - 开发者、软件架构师、教授、作者和演讲者
- **[佩德罗·诺克](https://compozy.com/)** - Compozy.com 创始人兼 CEO | 构建企业级下一代 AI 编排平台 | 使用 YAML 简化多代理系统 | 开源先驱
特别感谢他们的 AI for Development 课程，为这些模式和实践提供了基础。
## 📖 文档
有关特定组件的详细信息：
- **规则**：请参阅 `.claude/rules/` 中的各个文件
- **代理**：每个代理在 `.claude/agents/` 中都有全面的文档
- **模板**：`.claude/templates/` 中的标准文档模板
- **克劳德代码命令行界面**：[官方文档](https://docs.anthropic.com/en/docs/claude-code)
## 🤝 贡献
该框架遵循已建立的规则和标准。在贡献之前：
1. 查看 `.claude/rules/` 中的规则
2. 遵循 `.claude/rules/git-workflow.md` 中的 Git 工作流程
3. 使用约定提交
4. 确保所有测试均通过 `bun run test`
## 📄 许可证
该项目根据 MIT 许可证授权 - 有关详细信息，请参阅 [LICENSE](LICENSE) 文件。
---
_框架版本：2.0.0 | 最后更新：2025 年 8 月_
