CLAUDE.md

本文件为 AI 助手在此代码库中工作时提供上下文指导。

项目概览

核心功能：{{用 1-2 句话描述项目做什么}}

目录结构

{{项目根目录}}/
├── src/ # 源代码
├── tests/ # 测试代码
├── docs/ # 文档
├── config/ # 配置文件
├── scripts/ # 构建/部署脚本
├── {{业务模块}}/ # 业务相关目录
└── {{其他}}/ # 其他目录

开发命令

# 安装依赖
{{安装命令}}

# 启动开发环境
{{开发启动命令}}

# 运行测试
{{测试命令}}

# 构建生产版本
{{构建命令}}

# 代码检查
{{lint 命令}}
{{格式化命令}}

架构原则

分层约定

请求/输入 → 控制器/接口层 → 业务逻辑层 → 数据访问层 → 存储/外部服务

核心规范

1. 单一职责：每个模块/类只负责一件事
2. 依赖倒置：依赖抽象接口，不依赖具体实现
3. 配置分离：环境相关配置放入配置文件/环境变量
4. 错误处理：统一错误格式，记录日志，不泄露敏感信息

编码规范

命名约定

代码风格

• 缩进：{{2 空格 / 4 空格 / Tab}}
• 行宽：{{80 / 100 / 120}} 字符
• 引号：{{单引号 / 双引号}}
• 末尾分号：{{需要 / 不需要}}

注释规范

// 单行注释：解释"为什么"，不是"做什么"

/**
 * 多行注释/文档注释
 * @param 参数说明
 * @return 返回值说明
 */

测试规范

测试类型

测试命名

{{测试语言示例}}
// 格式：should_预期行为_当条件
test('should_return_user_when_id_exists')

测试覆盖率要求

• 行覆盖率：≥ {{80}}%
• 分支覆盖率：≥ {{70}}%
• 关键业务模块：100%

安全规范

必须遵守

• [ ] 用户输入必须验证和转义
• [ ] 敏感信息不写入日志
• [ ] 密码/密钥使用环境变量存储
• [ ] API 接口需要认证和授权
• [ ] 数据库查询使用参数化（防注入）

禁止行为

• 硬编码密钥/密码
• 明文存储敏感数据
• 跳过输入验证
• 在生产环境使用调试模式

依赖管理

依赖分类

版本策略

• 生产依赖：锁定具体版本（1.2.3）
• 开发依赖：可使用范围版本（^1.2.0）
• 定期更新：每月检查安全漏洞

Git 工作流

分支策略

main          # 生产分支（受保护）
develop       # 开发分支
feature/*     # 功能分支
bugfix/*      # 修复分支
release/*     # 发布分支

提交规范

<type>(<scope>): <subject>

# type: feat | fix | docs | style | refactor | test | chore
# scope: 影响范围（可选）
# subject: 简短描述

# 示例
feat(auth): add JWT token refresh endpoint
fix(api): resolve null pointer in user service
docs(readme): update installation guide

PR/MR 要求

• [ ] 代码通过所有测试
• [ ] 代码通过 lint 检查
• [ ] 有相关测试覆盖
• [ ] 更新相关文档
• [ ] 至少 1 人代码审查

文档规范

必须维护的文档

文档更新时机

• 新增功能 → 更新 README + API 文档
• 配置变更 → 更新部署指南
• 版本发布 → 更新变更日志

配置管理

环境分类

配置优先级

命令行参数 > 环境变量 > 配置文件 > 默认值

问题排查

日志级别

常见问题

部署流程

发布检查清单

• [ ] 所有测试通过
• [ ] 代码审查完成
• [ ] 文档已更新
• [ ] 配置已同步
• [ ] 回滚方案准备

回滚策略

1. 保留最近 {{3}} 个版本
2. 回滚命令：{{回滚命令}}
3. 数据迁移回滚：{{迁移回滚命令}}

附加资源