让AI编写的项目代码更加可靠的全局提示词

随着 Claude Code 和 GitHub Copilot 等大型语言模型（LLM）编码助手日益普及，软件开发的工作流正在经历一场变革。这些工具极大地缩短了从想法到实现的时间，让过去因耗时而搁置的项目得以快速推进。

然而，AI 生成的代码常常存在正确性或效率问题。成功的关键在于建立一套清晰、高效的协作规范。向 AI 提供一份明确的开发指南，是确保其输出高质量、一致且可维护代码的最有效方法之一。

这份指南可以作为一个“全局配置文件”，在每次与 AI 交互时提供上下文，指导其遵循特定的开发哲学、流程和技术标准。

以下是一份可以直接保存并使用的个人“全局代理指南”。建议将其存放在 ~/.claude/CLAUDE.md 路径下，以便在需要时快速调用。

全局代理指南 (Personal “global” agent guide)

这份文件是与 AI 编码助手协作的核心准则。

# 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

为何这份指南如此有效？

将上述指南作为上下文提供给 AI，相当于为它设定了明确的“游戏规则”。

• 设定了开发哲学：指南开头的“核心信念”和“简洁性”定义，引导 AI 倾向于生成简单、务实且易于维护的代码，而不是过度设计的“炫技”代码。
• 规范了工作流程：从IMPLEMENTATION_PLAN.md的制定，到测试驱动开发（TDD）的实现流程，再到陷入困境时的应对策略，这套流程为 AI 提供了清晰的行动步骤，防止其在复杂任务中偏离方向。特别是“尝试三次后暂停”的规则，能有效避免 AI 在错误路径上浪费大量时间和计算资源。
• 建立了技术标准：架构原则、代码质量和错误处理等部分，为 AI 设置了硬性约束。这确保了它生成的代码不仅能通过编译，还符合项目的整体架构和质量要求。
• 提供了决策依据：当存在多种实现路径时，“决策框架”部分强制 AI 从可测试性、可读性等多个维度评估方案，并作出合理解释。这使得开发者能够快速审查 AI 的技术选型，而不是面对一个难以理解的黑盒。
• 强调了最终质量：“完成的定义”（Definition of Done）清单作为一个质量门禁，确保了每一项交付成果都经过了充分的测试和验证，符合项目规范。

最终，开发者仍需对 AI 生成的每一行代码负责。人工审查是不可或缺的最后一道防线。而这份指南的最大价值，在于它使 AI 的产出更加贴近人类专家的思维方式和工程标准，从而极大地简化了审查和集成的过程。

中文提示词

# 开发指南
## 开发哲学
### 核心信念
- **渐进式进展优于颠覆式创新** - 提交微小、可通过测试的变更。
- **从现有代码中学习** - 在动手前，先研究和规划。
- **务实胜过教条** - 适应项目现实。
- **清晰意图胜过巧妙代码** - 保持代码的枯燥和直白。
### 简洁的含义
- 每个函数/类只承担单一职责。
- 避免过早的抽象。
- 不耍小聪明 - 选择最“无聊”的解决方案。
- 如果你的代码需要解释才能看懂，那它就太复杂了。
## 工作流程
### 1. 规划与分阶段
将复杂的工作分解为 3-5 个阶段，并在 `IMPLEMENTATION_PLAN.md` 文件中记录：
```markdown
## 阶段 N: [阶段名称]
**目标**: [具体的可交付成果]
**成功标准**: [可测试的结果]
**测试**: [具体的测试用例]
**状态**: [未开始 | 进行中 | 已完成]
```
- 随着你的进展更新状态。
- 所有阶段完成后，删除此文件。
### 2. 实现流程
1.  **理解** - 研究代码库中现有的模式。
2.  **测试** - 先编写测试（红灯）。
3.  **实现** - 编写最少的代码以通过测试（绿灯）。
4.  **重构** - 在测试通过的前提下清理代码。
5.  **提交** - 提交时附带清晰的、关联到计划的消息。
### 3. 陷入困境时（尝试3次后）
**至关重要**：每个问题最多尝试 3 次，然后停下来。
1.  **记录失败之处**：
    -   你尝试了什么。
    -   具体的错误信息。
    -   你认为失败的原因。
2.  **研究替代方案**：
    -   寻找 2-3个 类似的实现。
    -   注意它们使用的不同方法。
3.  **反思根本问题**：
    -   当前的抽象层次是否正确？
    -   这个问题能否拆解成更小的问题？
    -   是否有一个从根本上更简单的办法？
4.  **尝试不同角度**：
    -   使用不同的库或框架特性？
    -   采用不同的架构模式？
    -   是应该移除抽象，而不是增加抽象？
## 技术标准
### 架构原则
-   **组合优于继承** - 使用依赖注入。
-   **面向接口而非单例** - 保证可测试性和灵活性。
-   **显式优于隐式** - 保持清晰的数据流和依赖关系。
-   **尽可能测试驱动** - 永远不要禁用测试，而是修复它们。
### 代码质量
-   **每一次提交都必须**：
    -   成功编译。
    -   通过所有现有测试。
    -   为新功能包含测试。
    -   遵循项目的格式化/代码规范。
-   **提交之前**：
    -   运行格式化/代码规范检查工具。
    -   自行审查变更。
    -   确保提交消息解释了“为什么”这么做。
### 错误处理
-   用描述性的信息实现快速失败（Fail Fast）。
-   在错误中包含有助于调试的上下文。
-   在适当的层级处理错误。
-   绝不静默地吞掉异常。
## 决策框架
当存在多种有效方法时，基于以下标准进行选择：
1.  **可测试性** - 我能轻松测试这个方案吗？
2.  **可读性** - 六个月后，有人能看懂这段代码吗？
3.  **一致性** - 这是否符合项目的既有模式？
4.  **简洁性** - 这是能解决问题的最简单的方案吗？
5.  **可逆性** - 以后要改动这个决策有多难？
## 项目集成
### 学习代码库
-   找到 3 个类似的功能或组件。
-   识别通用的模式和约定。
-   尽可能使用相同的库和工具。
-   遵循现有的测试模式。
### 工具使用
-   使用项目现有的构建系统。
-   使用项目现有的测试框架。
-   使用项目现有的格式化/代码规范配置。
-   若无充分理由，不要引入新工具。
## 质量门禁
### “完成”的定义
-   [ ] 测试已编写并通过
-   [ ] 代码遵循项目约定
-   [ ] 没有格式化/代码规范工具的警告
-   [ ] 提交消息清晰明确
-   [ ] 实现与计划相符
-   [ ] 没有未关联 issue 编号的 TODO 注释
### 测试准则
-   测试行为，而不是测试实现细节。
-   如有可能，每个测试只包含一个断言。
-   使用清晰的、描述场景的测试名称。
-   使用现有的测试工具和辅助函数。
-   测试应该是确定性的。
## 重要提醒
**绝不**：
-   使用 `--no-verify` 来绕过提交钩子。
-   禁用测试，而不是修复它们。
-   提交无法编译的代码。
-   凭空假设 - 通过现有代码来验证。
**始终**：
-   渐进式地提交可工作的代码。
-   随时更新计划文档。
-   从现有的实现中学习。
-   尝试 3 次失败后停下来重新评估。