Claude Code 最佳实践完全指南

我过去几个月一直在试验 LLM 编程 agent。Claude Code 成了我的最爱。

它虽然不是完美无缺，但让我在相对较短的时间内写了约 12 个程序/项目，我觉得没有它的话，不可能在同样的时间内完成这么多工作。其实大部分项目，如果没有 Claude Code，我根本不会费力去写，因为它们会占用太多时间。（本文末尾附有列表。）

我还远不是 Claude Code 的专家，积压了很多博文和文档需要复习，这些可能会很有用。但——这一点最关键——你不需要读遍所有资料才能开始看到成果。你甚至不需要读这篇文章；只需在里面输入一些 prompt 看看会出什么就行。

不过，既然我刚为求职申请写了这些内容，这里就是我如何从 Claude Code 中获得好结果的方法。我在适当的地方添加了一些例子的链接。

关键是提前编写清晰的规范，为 agent 在代码库中的工作提供上下文。（例子：1, 2, 3, 4）

为 agent 准备一份文档，概述项目的结构以及如何运行构建和 linter 这样的东西会很有帮助。（例子：1, 2, 3）

要求 agent 对自己的工作进行代码审查，这出乎意料地富有成效。

最后，我有一份个人的"全局" agent 指南，描述 agent 应遵循的最佳实践，指定问题解决方法、TDD 的使用等内容。（这个文件在本文末尾附近列出。）

然后就是验证 LLM 生成的代码的问题。

AI 生成的代码经常是不正确或低效的。

对我来说，重要的是要指出：我认为无论代码是如何生成的，我最终都对进入带有我名字的 PR 中的代码负责。

因此，尤其是在任何专业环境中，我都会手动审查所有 AI 生成的代码和测试用例。对于我认为缺失或需要改进的任何东西，我都会添加测试用例，可以手动添加，也可以要求 LLM 编写这些用例（我随后会审查）。

归根结底，需要手动审查来验证行为是否实现正确以及测试是否充分。

个人"全局" agent 指南

这放在 ~/.claude/CLAUDE.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`:

```markdown
## 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

## 使用 Claude Code 编写的项目

[原文在此处未提供项目列表]