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

• 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)

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

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

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

• 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

• Commit working code incrementally

• Update plan documentation as you go

• Learn from existing implementations

• Stop after 3 failed attempts and reassess

开发指南

哲学思想

核心理念

• 增量进步胜过重构 - 小的变更能够编译并通过测试

• 从现有代码中学习 - 在实施之前进行研究和规划

• 务实胜过教条 - 适应项目实际情况

• 明确意图胜过巧妙代码 - 保持无聊和明显

简单意味着

• 每个函数/类承担单一职责

• 避免过早抽象

• 不使用巧妙的技巧 - 选择无聊的解决方案

• 如果你需要解释它，那就太复杂了

流程

1. 规划与分阶段

• 随着进展更新状态

• 所有阶段完成后删除文件

2. 实施流程

1. 理解 - 研究代码库中的现有模式

2. 测试 - 首先编写测试（红色）

3. 实施 - 编写通过测试的最小代码（绿色）

4. 重构 - 在测试通过的情况下进行清理

5. 提交 - 使用链接到计划的清晰消息

3. 遇到困难时（3次尝试后）

1. 记录失败内容：
• 你尝试了什么
• 具体错误消息
• 你认为失败的原因

2. 研究替代方案：
• 找到2-3个类似实现
• 记录使用的不同方法

3. 质疑基础原理：
• 这是正确的抽象级别吗？
• 这能分解为更小的问题吗？
• 是否有完全更简单的方法？

4. 尝试不同角度：
• 不同的库/框架特性？
• 不同的架构模式？
• 移除抽象而不是增加？

技术标准

架构原则

• 组合优于继承 - 使用依赖注入

• 接口优于单例 - 启用测试和灵活性

• 显式优于隐式 - 清晰的数据流和依赖关系

• 尽可能测试驱动 - 永远不要禁用测试，要修复它们

代码质量

• 每次提交必须：
• 成功编译
• 通过所有现有测试
• 包含新功能的测试
• 遵循项目格式/代码检查规范

• 提交前：
• 运行格式化器/代码检查器
• 自我审查变更
• 确保提交消息解释"为什么"

错误处理

• 快速失败并提供描述性消息

• 包含调试上下文

• 在适当级别处理错误

• 永远不要静默吞咽异常

决策框架

1. 可测试性 - 我能轻松测试这个吗？

2. 可读性 - 6个月后有人能理解这个吗？

3. 一致性 - 这符合项目模式吗？

4. 简单性 - 这是有效的最简单解决方案吗？

5. 可逆性 - 以后更改有多困难？

项目集成

学习代码库

• 找到3个类似的功能/组件

• 识别通用模式和约定

• 尽可能使用相同的库/工具

• 遵循现有测试模式

工具

• 使用项目现有的构建系统

• 使用项目的测试框架

• 使用项目的格式化器/代码检查器设置

• 没有充分理由不要引入新工具

质量门禁

完成定义

测试指南

• 测试行为，不测试实现

• 尽可能每个测试一个断言

• 清晰的测试名称描述场景

• 使用现有测试工具/助手

• 测试应该是确定性的

重要提醒

• 使用 -no-verify 绕过提交钩子

• 禁用测试而不是修复它们

• 提交不能编译的代码

• 做假设 - 用现有代码验证

• 增量提交可工作的代码

• 在进行过程中更新计划文档

• 从现有实现中学习

• 3次失败尝试后停止并重新评估

转自原链接: https://github.com/LichAmnesia/GPT-Prompt-Hub/blob/main/CLAUDE.md