引言
仓库源码地址：https://github.com/affaan-m/everything-claude-code
本文来自 Anthropic 黑客马拉松获胜者的完整 Claude Code 配置集合，该仓库包含：生产级代理、技能、钩子、命令、规则和 MCP 配置，经过 10 多个月构建真实产品的密集日常使用而演化，本文主要记录 Rules 模块。
本文不讲废话，直接上示例，大家可以直接根据目录导航来根据需要查看实际的生产配置，相关概念目录如下：
- Git流程（git-workflow）
- 代理（agents）
- 安全（security）
- 性能（performance）
- 模式（patterns）
- 测试（testing）
- 编码风格（coding-style）
- 钩子（hooks）
Git流程（git-workflow）
# Git 工作流程 ## Commit 讯息格式 ``` : ``` 类型：feat、fix、refactor、docs、test、chore、perf、ci 注意：归属透过 ~/.claude/settings.json 全域停用。 ## Pull Request 工作流程 建立 PR 时： 1. 分析完整 commit 历史（不只是最新 commit） 2. 使用 `git diff [base-branch]...HEAD` 查看所有变更 3. 起草全面的 PR 摘要 4. 包含带 TODO 的测试计划 5. 如果是新分支，使用 `-u` flag 推送 ## 功能实作工作流程 1. **先规划** - 使用 **planner** Agent 建立实作计划 - 识别相依性和风险 - 拆解为阶段 2. **TDD 方法** - 使用 **tdd-guide** Agent - 先撰写测试（RED） - 实作使测试通过（GREEN） - 重构（IMPROVE） - 验证 80%+ 覆盖率 3. **程式码审查** - 撰写程式码后立即使用 **code-reviewer** Agent - 处理关键和高优先问题 - 尽可能修复中优先问题 4. **Commit 与推送** - 详细的 commit 讯息 - 遵循 conventional commits 格式代理（agents）
# Agent 协调 ## 可用 Agents 位于 `~/.claude/agents/`： | Agent | 用途 | 何时使用 | |-------|------|----------| | planner | 实作规划 | 复杂功能、重构 | | architect | 系统设计 | 架构决策 | | tdd-guide | 测试驱动开发 | 新功能、Bug 修复 | | code-reviewer | 程式码审查 | 撰写程式码后 | | security-reviewer | 安全性分析 | 提交前 | | build-error-resolver | 修复建置错误 | 建置失败时 | | e2e-runner | E2E 测试 | 关键使用者流程 | | refactor-cleaner | 无用程式码清理 | 程式码维护 | | doc-updater | 文件 | 更新文件 | ## 立即使用 Agent 不需要使用者提示： 1. 复杂功能请求 - 使用 **planner** Agent 2. 刚撰写/修改程式码 - 使用 **code-reviewer** Agent 3. Bug 修复或新功能 - 使用 **tdd-guide** Agent 4. 架构决策 - 使用 **architect** Agent ## 平行任务执行 对独立操作总是使用平行 Task 执行： ```markdown # 好：平行执行 平行启动 3 个 agents： 1. Agent 1：auth.ts 的安全性分析 2. Agent 2：快取系统的效能审查 3. Agent 3：utils.ts 的型别检查 # 不好：不必要的循序 先 agent 1，然后 agent 2，然后 agent 3 ``` ## 多观点分析 对于复杂问题，使用分角色子 agents： - 事实审查者 - 资深工程师 - 安全专家 - 一致性审查者 - 冗余检查者安全（security）
# 安全性指南 ## 强制安全性检查 任何提交前： - [ ] 没有写死的密钥（API 金钥、密码、Token） - [ ] 所有使用者输入已验证 - [ ] SQL 注入防护（参数化查询） - [ ] XSS 防护（清理过的 HTML） - [ ] 已启用 CSRF 保护 - [ ] 已验证验证/授权 - [ ] 所有端点都有速率限制 - [ ] 错误讯息不会泄漏敏感资料 ## 密钥管理 ```typescript // 绝不：写死的密钥 const apiKey = "sk-proj-xxxxx" // 总是：环境变数 const apiKey = process.env.OPENAI_API_KEY if (!apiKey) { throw new Error('OPENAI_API_KEY not configured') } ``` ## 安全性回应协定 如果发现安全性问题： 1. 立即停止 2. 使用 **security-reviewer** Agent 3. 在继续前修复关键问题 4. 轮换任何暴露的密钥 5. 审查整个程式码库是否有类似问题性能（performance）
# 效能优化 ## 模型选择策略 **Haiku 4.5**（Sonnet 90% 能力，3 倍成本节省）： - 频繁呼叫的轻量 agents - 配对程式设计和程式码产生 - 多 agent 系统中的 worker agents **Sonnet 4.5**（最佳程式码模型）： - 主要开发工作 - 协调多 agent 工作流程 - 复杂程式码任务 **Opus 4.5**（最深度推理）： - 复杂架构决策 - 最大推理需求 - 研究和分析任务 ## 上下文视窗管理 避免在上下文视窗的最后 20% 进行： - 大规模重构 - 跨多个档案的功能实作 - 除错复杂互动 较低上下文敏感度任务： - 单档案编辑 - 独立工具建立 - 文件更新 - 简单 Bug 修复 ## Ultrathink + Plan 模式 对于需要深度推理的复杂任务： 1. 使用 `ultrathink` 增强思考 2. 启用 **Plan 模式** 以结构化方法 3. 用多轮批评「预热引擎」 4. 使用分角色子 agents 进行多元分析 ## 建置疑难排解 如果建置失败： 1. 使用 **build-error-resolver** Agent 2. 分析错误讯息 3. 增量修复 4. 每次修复后验证模式（patterns）
# 常见模式 ## API 回应格式 ```typescript interface ApiResponse { success: boolean data?: T error?: string meta?: { total: number page: number limit: number } } ``` ## 自订 Hooks 模式 ```typescript export function useDebounce(value: T, delay: number): T { const [debouncedValue, setDebouncedValue] = useState(value) useEffect(() => { const handler = setTimeout(() => setDebouncedValue(value), delay) return () => clearTimeout(handler) }, [value, delay]) return debouncedValue } ``` ## Repository 模式 ```typescript interface Repository { findAll(filters?: Filters): Promise测试（testing）
# 测试需求 ## 最低测试覆盖率：80% 测试类型（全部必要）： 1. **单元测试** - 个别函式、工具、元件 2. **整合测试** - API 端点、资料库操作 3. **E2E 测试** - 关键使用者流程（Playwright） ## 测试驱动开发 强制工作流程： 1. 先撰写测试（RED） 2. 执行测试 - 应该失败 3. 撰写最小实作（GREEN） 4. 执行测试 - 应该通过 5. 重构（IMPROVE） 6. 验证覆盖率（80%+） ## 测试失败疑难排解 1. 使用 **tdd-guide** Agent 2. 检查测试隔离 3. 验证 mock 是否正确 4. 修复实作，而非测试（除非测试是错的） ## Agent 支援 - **tdd-guide** - 主动用于新功能，强制先撰写测试 - **e2e-runner** - Playwright E2E 测试专家编码风格（coding-style）
# 程式码风格 ## 不可变性（关键） 总是建立新物件，绝不变异： ```javascript // 错误：变异 function updateUser(user, name) { user.name = name // 变异！ return user } // 正确：不可变性 function updateUser(user, name) { return { ...user, name } } ``` ## 档案组织 多小档案 > 少大档案： - 高内聚、低耦合 - 通常 200-400 行，最多 800 行 - 从大型元件中抽取工具 - 依功能/领域组织，而非依类型 ## 错误处理 总是全面处理错误： ```typescript try { const result = await riskyOperation() return result } catch (error) { console.error('Operation failed:', error) throw new Error('Detailed user-friendly message') } ``` ## 输入验证 总是验证使用者输入： ```typescript import { z } from 'zod' const schema = z.object({ email: z.string().email(), age: z.number().int().min(0).max(150) }) const validated = schema.parse(input) ``` ## 程式码品质检查清单 在标记工作完成前： - [ ] 程式码可读且命名良好 - [ ] 函式小（<50 行） - [ ] 档案专注（<800 行） - [ ] 没有深层巢状（>4 层） - [ ] 适当的错误处理 - [ ] 没有 console.log 陈述式 - [ ] 没有写死的值 - [ ] 没有变异（使用不可变模式）钩子（hooks）
# Hook 系统 ## Hook 类型 - **PreToolUse**：工具执行前（验证、参数修改） - **PostToolUse**：工具执行后（自动格式化、检查） - **Stop**：工作阶段结束时（最终验证） ## 目前 Hooks（在 ~/.claude/settings.json） ### PreToolUse - **tmux 提醒**：建议对长时间执行的指令使用 tmux（npm、pnpm、yarn、cargo 等） - **git push 审查**：推送前开启 Zed 进行审查 - **文件阻挡器**：阻挡建立不必要的 .md/.txt 档案 ### PostToolUse - **PR 建立**：记录 PR URL 和 GitHub Actions 状态 - **Prettier**：编辑后自动格式化 JS/TS 档案 - **TypeScript 检查**：编辑 .ts/.tsx 档案后执行 tsc - **console.log 警告**：警告编辑档案中的 console.log ### Stop - **console.log 稽核**：工作阶段结束前检查所有修改档案中的 console.log ## 自动接受权限 谨慎使用： - 对受信任、定义明确的计划启用 - 对探索性工作停用 - 绝不使用 dangerously-skip-permissions flag - 改为在 `~/.claude.json` 中设定 `allowedTools` ## TodoWrite 最佳实务 使用 TodoWrite 工具来： - 追踪多步骤任务的进度 - 验证对指示的理解 - 启用即时调整 - 显示细粒度实作步骤 待办清单揭示： - 顺序错误的步骤 - 缺少的项目 - 多余的不必要项目 - 错误的粒度 - 误解的需求
