CLAUDE.md

基础约定

• 语言：中文
• 环境：Windows / PowerShell
• 风格：技术导向、简洁明了、优雅高效
• 注释：必须有函数级注释

核心原则

1. 先理解，再编码

• 修改前必须完整阅读相关代码。
• 基于事实判断，禁止猜测。
• 不确定时必须说明疑问并询问。
• 存在多种理解时，先列出选项，不要静默选择。
• 涉及 Breaking Change，必须先确认。

2. 简单优先

• 采用最简单可行方案。
• 只实现明确需求，禁止额外功能。
• 禁止为单次使用代码设计抽象。
• 禁止引入无必要的灵活性、配置项或复杂模式。
• 优先使用成熟稳定库，避免重复造轮子。
• 优先级：正确性 > 可读性 > 性能；仅在确认瓶颈后优化。

3. 最小改动

• 只修改与需求直接相关的代码。
• 不做无收益的重构、格式化或风格调整。
• 不“顺手优化”相邻代码。
• 保持现有代码风格，即使不是最理想风格。
• 若发现无关问题，只说明，不擅自修改。
• 仅删除因本次改动产生的无用 imports、变量、函数或代码。

判断标准：每一行改动都应能直接对应用户需求。

4. 可验证执行

将任务转化为可验证目标：

• 修 Bug：先复现问题，再修改并验证。
• 加功能：明确输入、输出、边界条件与测试方式。
• 重构：确保修改前后行为一致，并运行相关测试。

多步骤任务需先给出简要计划：

1. [步骤] → 验证：[检查方式]
2. [步骤] → 验证：[检查方式]
3. [步骤] → 验证：[检查方式]

完成后必须说明：

• 修改了什么
• 为什么这样改
• 如何验证
• 是否存在风险或后续事项

5. CI/CD 规范

• AI 生成的提交信息必须添加 🤖 前缀。
• 提交前必须确保最小 CI/CD 流程可通过，至少验证：构建成功、核心测试通过、基础运行正常
• 项目必须包含最小可用 CI 配置：.github/workflows/ci.yml

成功标准

这些准则应带来：

• 更少无关 diff
• 更少过度复杂实现
• 更少返工
• 更早暴露不确定点
• 更稳定、可验证、易维护的代码改动