Claude Code 项目管理完全指南：CLAUDE.md 设计 + 进度追踪 + 长期任务管理Claude Code

Claude Code 项目管理完全指南：CLAUDE.md 设计 + 进度追踪 + 长期任务管理

系统介绍 Claude Code 的项目级配置方案，包括 CLAUDE.md 结构设计、分层规则系统、进度持久化策略。

概述

Claude Code 的项目管理能力来自三个层次：

Level 1: CLAUDE.md          → 项目级全局规则（每次会话自动读取）
Level 2: .claude/rules/     → 模块级详细规则（按需引用）
Level 3: PROGRESS.md        → 任务级进度状态（手动引用）

1. 快速初始化：`/init` 命令

用法

# 在项目根目录执行
/init

生成内容

Claude 会扫描并分析：

package.json / go.mod / requirements.txt（技术栈识别）
目录结构（约定推断）
代码风格（规范提取）
现有测试（测试框架识别）

生成 CLAUDE.md 草稿后，执行以下验证：

审查刚才生成的 CLAUDE.md：
1. 技术栈描述是否准确？
2. 关键命令是否正确？
3. 遗漏了哪些重要约定？

给出需要修改的地方

2. CLAUDE.md 完整模板

后端项目模板（Go）

# 项目名称

## 概述
[一句话描述项目目的]

## 技术栈
- 语言：Go 1.21
- Web 框架：Gin
- ORM：sqlx（直接 SQL，不用 GORM）
- 数据库：PostgreSQL 15
- 缓存：Redis 7
- 消息队列：Kafka
- 测试：testify + gomock
- CI/CD：GitHub Actions

## 目录结构

cmd/ 程序入口（main.go） internal/ 内部包（业务逻辑） ├── api/ HTTP handler ├── service/ 业务层 ├── repo/ 数据访问层 └── model/ 数据模型 pkg/ 可复用公共包 configs/ 配置文件 migrations/ 数据库迁移文件


## 关键命令
```bash
make run      # 本地运行（自动加载 .env）
make test     # 运行所有测试
make test-unit  # 仅单元测试
make lint     # golangci-lint
make migrate  # 执行数据库迁移
make mock     # 重新生成 mock 文件

编码规范

错误处理：errors.Wrap(err, "context message") 包装，不要 log.Fatal
日志：zerolog，不用 fmt.Printf 或 log 标准库
上下文：所有数据库/HTTP 操作必须传入 ctx，且带超时
测试：每个 handler 和 service 必须有单元测试

重要约束

禁止直接操作 production 数据库（用迁移文件）
禁止在代码中硬编码密钥或密码
所有 API 接口变更需更新 OpenAPI 文档（api/openapi.yaml）
数据库 schema 变更必须有对应的 migration 文件

特殊约定（偏离通用实践的地方）

不用 panic，即使在不应该发生的情况下
接口命名用名词不加 I 前缀（如 UserRepository 而非 IUserRepository）
错误信息统一用英文（日志给机器看）

历史踩坑

JWT 时区问题：所有时间计算用 time.Now().UTC()，详见 pkg/jwt/
Redis 连接泄漏：每次 Scan 后必须关闭游标，见 pkg/cache/scan.go


### 前端项目模板（React/TypeScript）

```markdown
# 前端项目名称

## 技术栈
- React 18 + TypeScript 5
- 状态管理：Zustand
- 路由：React Router v6
- 样式：Tailwind CSS
- 构建：Vite
- 测试：Vitest + Testing Library
- 代码质量：ESLint + Prettier

## 关键命令
```bash
pnpm dev      # 开发服务器（默认 :3000）
pnpm build    # 生产构建
pnpm test     # 运行测试
pnpm lint     # ESLint 检查
pnpm type-check  # tsc --noEmit

组件约定

组件文件：PascalCase（UserProfile.tsx）
Hook 文件：camelCase with use 前缀（useAuthStore.ts）
状态管理：全局状态用 Zustand store，局部状态用 useState
样式：只用 Tailwind，禁止内联 style（除非动态值）

禁止事项

禁止 any 类型（用 unknown + 类型守卫）
禁止直接修改 props
禁止在 useEffect 里直接 mutate state

验证要求

完成任何改动后：

pnpm type-check（无类型错误）
pnpm lint（无 lint 错误）
pnpm test（相关测试通过）


---

## 3. 分层规则系统

### 目录结构

.claude/ ├── rules/ │ ├── security.md # 安全规范 │ ├── database.md # 数据库操作规范 │ ├── api-design.md # API 设计规范 │ └── testing.md # 测试规范 └── templates/ # 代码模板（可选） ├── handler.go.tpl └── service.go.tpl


### security.md 示例

```markdown
# 安全规范

## 认证
- JWT 验证必须检查：签名、过期时间、issuer、audience
- Refresh token 必须存储在 HttpOnly Cookie
- 所有敏感操作需要重新验证（修改密码、删除账户）

## 输入验证
- 所有用户输入在 handler 层验证，使用 validator 包
- 文件上传：检查 MIME type（不只是扩展名）、大小限制
- SQL：所有查询使用参数化，禁止字符串拼接

## 错误响应
- 生产环境不返回堆栈跟踪
- 认证失败统一返回 401（不区分"用户不存在"和"密码错误"）
- 权限不足返回 403

## 敏感数据
- 日志中不打印密码、token、信用卡号
- API 响应中不返回 password 字段（即使是 hash）

在 CLAUDE.md 中引用

## 详细规范
详细安全规范：@.claude/rules/security.md
数据库操作规范：@.claude/rules/database.md

4. PROGRESS.md 进度追踪

生成进度文件

在每次会话结束前：

把今天的工作状态写入 PROGRESS.md，包括：
1. 已完成的功能（列清楚文件路径）
2. 进行中的工作和当前进展
3. 待开始的任务
4. 本次会话做的关键架构/设计决策
5. 已知的 bug 或技术债

PROGRESS.md 格式模板

# 开发进度

更新时间：2026-03-30

## 当前迭代：v2.3.0

### ✅ 已完成
- 用户注册/登录 API（src/api/auth.go）
- JWT 中间件（src/middleware/auth.go）
- 用户 CRUD（src/api/user.go + src/service/user.go）

### 🔄 进行中
- 权限管理模块（50% 完成）
  - 已完成：数据库 schema、角色 CRUD API
  - 进行中：权限检查中间件（src/middleware/permission.go）
  - 待完成：权限继承逻辑

### 📋 待开始
- 审计日志
- 用户组功能
- 前端对接

### 🏛️ 关键决策
- 权限模型选择 RBAC（理由：当前业务不需要 ABAC 的复杂性）
- 权限缓存时间：5 分钟（Redis，key 格式：`perm:{userId}`）

### 🐛 已知问题
- 角色继承目前最多 3 层，超过会无限递归（需要 DFS 改 BFS）
- 测试覆盖率 permission.go 只有 60%，需要补充

恢复进度

# 新会话开始时
"参考 @PROGRESS.md 了解当前进度，
继续实现权限管理模块的下一步：权限检查中间件"

5. ROADMAP.md 活文档

对于长期项目，让 Claude 维护 ROADMAP：

每完成一个功能，更新 @ROADMAP.md：
- 标记已完成的里程碑
- 更新预计完成时间（如果有变化）
- 记录本次功能对整体架构的影响

6. 最佳实践总结

CLAUDE.md 写作原则

✅ 写什么：
- 偏离通用最佳实践的约定
- 项目特有的工具链和命令
- 每次会话都适用的全局规则
- 历史踩坑和避坑方法

❌ 不写什么：
- 通用编程最佳实践（Claude 已经知道）
- 只在特定场景适用的临时规则
- 代码片段（用 @引用文件代替）
- 超过 300 行的内容

文件大小控制

主 CLAUDE.md：< 200 行
各 .claude/rules/ 文件：< 100 行
PROGRESS.md：无限制（但旧内容定期归档）

API 集成配置

项目级配置推荐写入 .env.local（不提交到 git）：

# .env.local
ANTHROPIC_BASE_URL=https://ccaihub.com/v1
ANTHROPIC_API_KEY=your-ccaihub-key

ccaihub支持 Claude 全系列模型，接口兼容官方，适合团队统一使用。

点赞收藏，CLAUDE.md 模板直接复用。有更好的项目管理方案欢迎评论。

Claude Code 项目管理完全指南：CLAUDE.md 设计 + 进度追踪 + 长期任务管理