原文：Chris Dzombak - 2025.08.08
在过去的几个月里，我一直在尝试各种大语言模型（LLM）编程代理。Claude Code 已经成了我的最爱。
虽然它并非没有缺点，但它让我在相对较短的时间内完成了大约 12 个程序/项目。如果没有它，我不可能在同样的时间内完成这么多工作。其中大部分项目，如果不是因为有 Claude Code，我可能根本就不会费心去写，因为它们会占用太多的时间。
我远非 Claude Code 专家，还有一大堆博客文章和文档等着我去学习，它们可能很有用。但是 ------ 这一点至关重要 ------ 你不需要读遍所有资料才能看到效果。你甚至都不需要读这篇文章；直接输入一些提示，看看会得到什么结果就行。
话虽如此，因为我刚刚为一次求职申请整理了这些内容，所以在这里分享一下我是如何让 Claude Code 发挥出色的。
- 关键在于提前编写一份清晰的需求说明（spec），这能为代理在代码库中工作时提供上下文。
- 为代理准备一份文档，概述项目结构以及如何运行构建（build）和代码检查工具（linter）等命令，会很有帮助。
- 让代理对自己写的代码进行代码审查（code review），效果出奇地好。
- 最后，我有一个个人的"全局"代理指南，描述了代理应遵循的最佳实践，规定了诸如解决问题的思路、测试驱动开发（TDD）的使用等。(该文件内容附于本文末尾。)
接下来是验证大语言模型（LLM）所写代码的问题。
人工智能生成的代码确实 常常不正确或效率低下。
我必须强调一点：我相信，无论代码是如何生成的，最终提交到带有我名字的合并请求（PR）中的代码，都由我责任到底。
因此，尤其是在任何专业场景下，我都会手动审查所有 AI 编写的代码和测试用例。对于可能的缺失或需要改进的地方，我会添加测试用例，可以手动添加，也可以让 LLM 来写（写完后我审查）。
总而言之，手动审查是必要的，以验证代码行为是否被正确实现，以及是否得到了充分的测试。
个人"全局"代理指南
这份指南位于 ~/.claude/CLAUDE.md：
英文原文（中文翻译在下面）：
md
# Development Guidelines
## Philosophy
### Core Beliefs
- **Incremental progress over big bangs** - Small changes that compile and pass tests
- **Learning from existing code** - Study and plan before implementing
- **Pragmatic over dogmatic** - Adapt to project reality
- **Clear intent over clever code** - Be boring and obvious
### Simplicity Means
- Single responsibility per function/class
- Avoid premature abstractions
- No clever tricks - choose the boring solution
- If you need to explain it, it's too complex
## Process
### 1. Planning & Staging
Break complex work into 3-5 stages. Document in `IMPLEMENTATION_PLAN.md`:
## Stage N: [Name]
**Goal**: [Specific deliverable]
**Success Criteria**: [Testable outcomes]
**Tests**: [Specific test cases]
**Status**: [Not Started|In Progress|Complete]
- Update status as you progress
- Remove file when all stages are done
### 2. Implementation Flow
1. **Understand** - Study existing patterns in codebase
2. **Test** - Write test first (red)
3. **Implement** - Minimal code to pass (green)
4. **Refactor** - Clean up with tests passing
5. **Commit** - With clear message linking to plan
### 3. When Stuck (After 3 Attempts)
**CRITICAL**: Maximum 3 attempts per issue, then STOP.
1. **Document what failed**:
- What you tried
- Specific error messages
- Why you think it failed
2. **Research alternatives**:
- Find 2-3 similar implementations
- Note different approaches used
3. **Question fundamentals**:
- Is this the right abstraction level?
- Can this be split into smaller problems?
- Is there a simpler approach entirely?
4. **Try different angle**:
- Different library/framework feature?
- Different architectural pattern?
- Remove abstraction instead of adding?
## Technical Standards
### Architecture Principles
- **Composition over inheritance** - Use dependency injection
- **Interfaces over singletons** - Enable testing and flexibility
- **Explicit over implicit** - Clear data flow and dependencies
- **Test-driven when possible** - Never disable tests, fix them
### Code Quality
- **Every commit must**:
- Compile successfully
- Pass all existing tests
- Include tests for new functionality
- Follow project formatting/linting
- **Before committing**:
- Run formatters/linters
- Self-review changes
- Ensure commit message explains "why"
### Error Handling
- Fail fast with descriptive messages
- Include context for debugging
- Handle errors at appropriate level
- Never silently swallow exceptions
## Decision Framework
When multiple valid approaches exist, choose based on:
1. **Testability** - Can I easily test this?
2. **Readability** - Will someone understand this in 6 months?
3. **Consistency** - Does this match project patterns?
4. **Simplicity** - Is this the simplest solution that works?
5. **Reversibility** - How hard to change later?
## Project Integration
### Learning the Codebase
- Find 3 similar features/components
- Identify common patterns and conventions
- Use same libraries/utilities when possible
- Follow existing test patterns
### Tooling
- Use project's existing build system
- Use project's test framework
- Use project's formatter/linter settings
- Don't introduce new tools without strong justification
## Quality Gates
### Definition of Done
- [ ] Tests written and passing
- [ ] Code follows project conventions
- [ ] No linter/formatter warnings
- [ ] Commit messages are clear
- [ ] Implementation matches plan
- [ ] No TODOs without issue numbers
### Test Guidelines
- Test behavior, not implementation
- One assertion per test when possible
- Clear test names describing scenario
- Use existing test utilities/helpers
- Tests should be deterministic
## Important Reminders
**NEVER**:
- Use `--no-verify` to bypass commit hooks
- Disable tests instead of fixing them
- Commit code that doesn't compile
- Make assumptions - verify with existing code
**ALWAYS**:
- Commit working code incrementally
- Update plan documentation as you go
- Learn from existing implementations
- Stop after 3 failed attempts and reassess中文翻译后的 ~/.claude/CLAUDE.md：
md
# 开发指南
## 理念
### 核心信念
- **渐进式改进优于大爆炸式开发** - 小步迭代，确保每次变更都能编译并通地过测试
- **从现有代码中学习** - 在动手实现前，先研究和规划
- **务实胜于教条** - 适应项目的实际情况
- **意图清晰胜于代码巧妙** - 选择简单直白、易于理解的方式
### 简洁意味着
- 每个函数/类只负责单一职责
- 避免过早抽象
- 不用奇技淫巧 ------ 选择简单直接的方案
- 如果一段代码需要额外解释，那它就太复杂了
## 流程
### 1. 规划与分阶段
将复杂的工作分解为 3-5 个阶段。在 `IMPLEMENTATION_PLAN.md` 中记录：
## 阶段 N：[名称]
**目标**：[具体的可交付成果]
**成功标准**：[可测试的结果]
**测试**：[具体的测试用例]
**状态**：[未开始|进行中|已完成]
- 随着进度更新状态
- 所有阶段完成后删除该文件
### 2. 实现流程
1. **理解** - 研究代码库中现有的模式
2. **测试** - 先写测试（红灯）
3. **实现** - 用最少的代码让测试通过（绿灯）
4. **重构** - 在测试通过的前提下清理代码
5. **提交** - 提交信息要清晰，并关联到开发计划
### 3. 卡住时怎么办（尝试 3 次后）
**关键**：每个问题最多尝试 3 次，然后停下来。
1. **记录失败之处**：
- 你尝试了什么
- 具体的错误信息
- 你认为失败的原因
2. **研究替代方案**：
- 寻找 2-3 个类似的实现
- 注意它们使用的不同方法
3. **反思基本问题**：
- 当前的抽象层级是否合适？
- 能否拆分成更小的问题？
- 是否有从根本上更简单的方案？
4. **尝试不同角度**：
- 使用不同的库/框架特性？
- 采用不同的架构模式？
- 移除而非增加抽象？
## 技术标准
### 架构原则
- **组合优于继承** - 使用依赖注入
- **接口优于单例** - 便于测试和保证灵活性
- **显式优于隐式** - 保持清晰的数据流和依赖关系
- **尽可能测试驱动** - 绝不禁用测试，而是修复它们
### 代码质量
- **每次提交必须**：
- 成功编译
- 通过所有现有测试
- 为新功能添加测试
- 遵守项目的格式化/代码检查规范
- **提交前**：
- 运行格式化/代码检查工具
- 自我审查变更
- 确保提交信息解释了"为什么"
### 错误处理
- 快速失败，并提供描述性信息
- 包含用于调试的上下文
- 在适当的层级处理错误
- 绝不静默地吞掉异常
## 决策框架
当存在多种有效方法时，基于以下标准进行选择：
1. **可测试性** - 我能轻松地测试它吗？
2. **可读性** - 6 个月后还有人能看懂吗？
3. **一致性** - 这是否符合项目的既有模式？
4. **简洁性** - 这是能解决问题的最简单的方案吗？
5. **可逆性** - 以后修改的难度有多大？
## 项目集成
### 学习代码库
- 找到 3 个类似的功能/组件
- 识别通用的模式和约定
- 尽可能使用相同的库/工具
- 遵循现有的测试模式
### 工具链
- 使用项目现有的构建系统
- 使用项目现有的测试框架
- 使用项目现有的格式化/代码检查工具配置
- 没有充分理由，不要引入新工具
## 质量门禁
### 完成的定义
- [ ] 测试已编写并通过
- [ ] 代码遵循项目规范
- [ ] 没有代码检查/格式化警告
- [ ] 提交信息清晰
- [ ] 实现与计划相符
- [ ] 没有不带 issue 编号的 TODO
### 测试指南
- 测试行为，而非实现细节
- 尽可能每个测试只包含一个断言
- 测试名称清晰，能描述场景
- 使用现有的测试工具/辅助函数
- 测试应具有确定性
## 重要提醒
**绝不**：
- 使用 `--no-verify` 绕过提交钩子
- 禁用测试而不是修复它们
- 提交无法编译的代码
- 做假设 ------ 用现有代码来验证
**始终**：
- 渐进式地提交可工作的代码
- 随时更新计划文档
- 从现有的实现中学习
- 尝试 3 次失败后停下，重新评估