11-项目规划、测试、代码审查实战使用 Claude Code 完成软件工程全流程项目规划、测试驱动开发、代码审查与质量保障。一、AI 驱动项目管理概述1.1 全流程覆盖项目启动 ↓ 需求分析 → AI 辅助需求拆解 ↓ 技术方案 → AI 生成架构设计 ↓ 任务分解 → AI 生成任务清单 ↓ 开发实现 → AI 辅助编码 ↓ 测试验证 → AI 生成测试、运行测试 ↓ 代码审查 → AI 自动审查 ↓ 文档生成 → AI 生成技术文档 ↓ 项目交付1.2 Claude Code 在各阶段的作用阶段Claude Code 功能使用场景项目规划CLI 生成规划文件架构文档、任务清单开发实现批量代码生成多模块并行开发测试Sub Agent 批量生成测试完整测试套件代码审查Sub Agent 批量审查项目级代码审查二、项目规划阶段2.1 需求分析与拆解使用 Claude Code 进行需求分析我有一个项目想法做一个在线笔记应用 请帮我分析需求并生成详细的功能清单。 项目在线笔记应用(Online Notes App)Claude 输出## 需求分析### 核心功能1. 用户系统 - 注册/登录邮箱密码、OAuth - 个人资料管理 - 密码重置2. 笔记管理 - 创建/编辑/删除笔记 - 富文本编辑Markdown 支持 - 笔记分类文件夹/标签 - 搜索功能3. 协作功能 - 笔记分享链接/邀请 - 实时协作编辑 - 评论系统4. 高级功能 - 版本历史 - 导出PDF、Markdown - 自动保存 - 离线支持### 技术选型建议- 后端FastAPI PostgreSQL - 前端React TypeScript - 实时WebSocket / Socket.io - 部署Docker AWS/GCP2.2 技术方案设计生成架构文档基于刚才的需求分析生成技术架构文档1. 系统架构图2. 数据库设计3. API 设计4. 技术栈选型5. 部署架构 保存为 docs/architecture.md生成的架构文档结构# 在线笔记应用 - 技术架构 ## 1. 系统架构┌─────────────────────────────────────────────────┐│ 客户端层 ││ ┌──────────┐ ┌──────────┐ ┌──────────┐ ││ │ Web App │ │ Mobile │ │ Desktop │ ││ │ (React) │ │ (React │ │ (Electron)│ ││ └────┬─────┘ │ Native) │ └────┬─────┘ ││ └─────────┴──────────┴───────┘ │└─────────────────────────────────────────────────┘│ HTTPS↓┌─────────────────────────────────────────────────┐│ 网关层 ││ Nginx / AWS API Gateway │└─────────────────────────────────────────────────┘│↓┌─────────────────────────────────────────────────┐│ 应用层 ││ FastAPI (Python) ││ ┌──────────┐ ┌──────────┐ ┌──────────┐ ││ │ Auth │ │ Notes │ │ Share │ ││ │ Service │ │ Service │ │ Service │ ││ └──────────┘ └──────────┘ └──────────┘ │└─────────────────────────────────────────────────┘│↓┌─────────────────────────────────────────────────┐│ 数据层 ││ ┌──────────────┐ ┌──────────────┐ ││ │ PostgreSQL │ │ Redis │ ││ │ (主数据库) │ │ (缓存) │ ││ └──────────────┘ └──────────────┘ │└─────────────────────────────────────────────────┘## 2. 数据库设计 ### 2.1 用户表 (users) sql CREATE TABLE users ( id SERIAL PRIMARY KEY, email VARCHAR(255) UNIQUE NOT NULL, username VARCHAR(50) UNIQUE NOT NULL, hashed_password VARCHAR(255) NOT NULL, is_active BOOLEAN DEFAULT TRUE, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP );2.2 笔记表 (notes)CREATETABLEnotes(idSERIALPRIMARYKEY,titleVARCHAR(200)NOTNULL,contentTEXT,user_idINTEGERREFERENCESusers(id),folder_idINTEGERREFERENCESfolders(id),is_publicBOOLEANDEFAULTFALSE,created_atTIMESTAMPDEFAULTCURRENT_TIMESTAMP,updated_atTIMESTAMPDEFAULTCURRENT_TIMESTAMP);3. API 设计3.1 认证相关POST /api/v1/auth/register- 用户注册POST /api/v1/auth/login- 用户登录POST /api/v1/auth/refresh- 刷新 Token3.2 笔记管理GET /api/v1/notes- 获取笔记列表POST /api/v1/notes- 创建笔记GET /api/v1/notes/{id}- 获取笔记详情PUT /api/v1/notes/{id}- 更新笔记DELETE /api/v1/notes/{id}- 删除笔记4. 技术栈层次技术后端框架FastAPI 0.100ORMSQLAlchemy 2.0数据库PostgreSQL 15缓存Redis 7认证JWT bcrypt部署Docker Docker Compose### 2.3 任务分解与排期 **生成开发任务清单** bash 基于技术架构生成详细的开发任务清单 包括任务名称、优先级、预计工时、依赖关系。 保存为 docs/tasks.md生成的任务清单# 开发任务清单 ## Phase 1: 基础设施 (Week 1) | 任务 | 优先级 | 工时 | 负责人 | 依赖 | |------|--------|------|--------|------| | [ ] 项目初始化 | P0 | 4h | AI | - | | [ ] 数据库设计 | P0 | 4h | AI | - | | [ ] 配置管理 | P0 | 2h | AI | 项目初始化 | | [ ] 日志系统 | P1 | 2h | AI | 项目初始化 | | [ ] Docker 配置 | P1 | 4h | AI | - | ## Phase 2: 用户系统 (Week 1-2) | 任务 | 优先级 | 工时 | 依赖 | |------|--------|------|------| | [ ] User 模型 | P0 | 2h | 数据库设计 | | [ ] JWT 认证 | P0 | 4h | User 模型 | | [ ] 注册 API | P0 | 2h | JWT 认证 | | [ ] 登录 API | P0 | 2h | JWT 认证 | | [ ] 用户资料 API | P1 | 2h | 注册 API | | [ ] 密码重置 | P2 | 4h | 登录 API | ## Phase 3: 笔记功能 (Week 2-3) | 任务 | 优先级 | 工时 | 依赖 | |------|--------|------|------| | [ ] Note 模型 | P0 | 2h | User 模型 | | [ ] Folder 模型 | P0 | 2h | Note 模型 | | [ ] 笔记 CRUD API | P0 | 4h | Note 模型 | | [ ] 文件夹 API | P0 | 3h | Folder 模型 | | [ ] 搜索功能 | P1 | 4h | 笔记 CRUD | | [ ] 标签系统 | P1 | 3h | Note 模型 | ## Phase 4: 高级功能 (Week 4) | 任务 | 优先级 | 工时 | 依赖 | |------|--------|------|------| | [ ] 分享功能 | P1 | 4h | 笔记功能 | | [ ] 版本历史 | P2 | 6h | 笔记功能 | | [ ] 导出功能 | P2 | 4h | 笔记功能 | | [ ] WebSocket 实时协作 | P2 | 8h | 分享功能 | ## Phase 5: 测试与优化 (Week 4-5) | 任务 | 优先级 | 工时 | 依赖 | |------|--------|------|------| | [ ] 单元测试 | P0 | 8h | 所有功能 | | [ ] 集成测试 | P0 | 6h | 单元测试 | | [ ] 性能优化 | P1 | 4h | 测试完成 | | [ ] 部署配置 | P1 | 4h | 优化完成 |三、测试驱动开发3.1 测试策略规划使用 Claude Code 生成测试策略为在线笔记应用生成测试策略文档包括1. 测试金字塔单元、集成、E2E2. 测试覆盖率目标3. 关键测试场景4. 测试数据策略5. CI/CD 中的测试流程 保存为 docs/testing-strategy.md生成的测试策略# 测试策略文档 ## 1. 测试金字塔/\ / \ E2E 测试 (10%) - Playwright /____\ / \ 集成测试 (30%) - pytest TestClient /________\/ \ 单元测试 (60%) - pytest mock/____________\## 2. 覆盖率目标 | 模块 | 单元测试 | 集成测试 | 总覆盖率 | |------|----------|----------|----------| | models | 90% | - | 90% | | services | 85% | 70% | 95% | | routers | 80% | 80% | 95% | | utils | 90% | - | 90% | ## 3. 关键测试场景 ### 3.1 认证模块 - [ ] 用户注册成功 - [ ] 注册时邮箱已存在 - [ ] 登录成功 - [ ] 登录时密码错误 - [ ] Token 过期处理 ### 3.2 笔记模块 - [ ] 创建笔记成功 - [ ] 创建笔记时标题为空 - [ ] 更新自己的笔记 - [ ] 更新他人的笔记权限检查 - [ ] 删除笔记 - [ ] 搜索笔记 ### 3.3 并发场景 - [ ] 同时编辑同一笔记 - [ ] 高并发下的数据一致性3.2 生成测试框架代码生成测试基础设施1. tests/conftest.py - pytest fixtures2. tests/factories.py - 测试数据工厂3. tests/utils.py - 测试工具函数4. .github/workflows/test.yml - CI 配置生成的conftest.py# tests/conftest.pyimportasyncioimportpytestimportpytest_asynciofromhttpximportAsyncClientfromsqlalchemy.ext.asyncioimportAsyncSession,create_async_enginefromsqlalchemy.ormimportsessionmakerfromapp.mainimportappfromapp.databaseimportBase,get_dbfromapp.models.userimportUserfromapp.utils.securityimportget_password_hash# 测试数据库TEST_DATABASE_URLpostgresqlasyncpg://test:testlocalhost/test_dbenginecreate_async_engine(TEST_DATABASE_URL)TestingSessionLocalsessionmaker(engine,class_AsyncSession,expire_on_commitFalse)pytest_asyncio.fixture(scopesession)defevent_loop():Create an instance of the default event loop for each test case.loopasyncio.get_event_loop_policy().new_event_loop()yieldloop loop.close()pytest_asyncio.fixture(scopesession,autouseTrue)asyncdefsetup_database():创建测试数据库表asyncwithengine.begin()asconn:awaitconn.run_sync(Base.metadata.create_all)yieldasyncwithengine.begin()asconn:awaitconn.run_sync(Base.metadata.drop_all)pytest_asyncio.fixtureasyncdefdb_session():获取测试数据库会话asyncwithTestingSessionLocal()assession:yieldsession# 清理数据awaitsession.rollback()pytest_asyncio.fixtureasyncdefasync_client(db_session):获取测试客户端asyncdefoverride_get_db():yielddb_session app.dependency_overrides[get_db]override_get_dbasyncwithAsyncClient(appapp,base_urlhttp://test)asclient:yieldclient app.dependency_overrides.clear()pytest_asyncio.fixtureasyncdeftest_user(db_session):创建测试用户userUser(emailtestexample.com,usernametestuser,hashed_passwordget_password_hash(testpassword),is_activeTrue)db_session.add(user)awaitdb_session.commit()awaitdb_session.refresh(user)returnuserpytest_asyncio.fixtureasyncdefauth_headers(async_client,test_user):获取认证 headersresponseawaitasync_client.post(/api/v1/auth/login,json{username:test_user.username,password:testpassword})tokenresponse.json()[access_token]return{Authorization:fBearer{token}}3.3 批量生成单元测试使用 Sub Agent 并行生成并行生成单元测试 任务1 - 生成认证模块测试 创建 tests/test_auth.py测试 - 注册成功/失败场景 - 登录成功/失败场景 - Token 验证 任务2 - 生成笔记模块测试 创建 tests/test_notes.py测试 - CRUD 操作 - 权限检查 - 搜索功能 任务3 - 生成分类模块测试 创建 tests/test_folders.py测试 - 文件夹 CRUD - 文件夹与笔记关系 所有测试使用 pytest-asyncio遵循 AAA 模式。生成的测试示例# tests/test_auth.pyimportpytestfromhttpximportAsyncClientfromsqlalchemy.ext.asyncioimportAsyncSessionfromapp.models.userimportUserpytest.mark.asyncioclassTestAuth:认证模块测试asyncdeftest_register_success(self,async_client:AsyncClient,db_session:AsyncSession):测试用户注册成功# Arrangeuser_data{email:newuserexample.com,username:newuser,password:password123}# Actresponseawaitasync_client.post(/api/v1/auth/register,jsonuser_data)# Assertassertresponse.status_code201dataresponse.json()assertdata[email]user_data[email]assertdata[username]user_data[username]assertidindata# 验证数据库userawaitdb_session.get(User,data[id])assertuserisnotNoneassertuser.emailuser_data[email]asyncdeftest_register_duplicate_email(self,async_client:AsyncClient,test_user:User):测试注册时邮箱已存在# Arrangeuser_data{email:test_user.email,# 已存在的邮箱username:anotheruser,password:password123}# Actresponseawaitasync_client.post(/api/v1/auth/register,jsonuser_data)# Assertassertresponse.status_code400assertemail already existsinresponse.json()[detail].lower()asyncdeftest_login_success(self,async_client:AsyncClient,test_user:User):测试登录成功# Actresponseawaitasync_client.post(/api/v1/auth/login,json{username:test_user.username,password:testpassword})# Assertassertresponse.status_code200dataresponse.json()assertaccess_tokenindataasserttoken_typeindataassertdata[token_type]bearerasyncdeftest_login_wrong_password(self,async_client:AsyncClient,test_user:User):测试密码错误# Actresponseawaitasync_client.post(/api/v1/auth/login,json{username:test_user.username,password:wrongpassword})# Assertassertresponse.status_code4013.4 运行测试与分析自动化测试流程运行所有测试并生成报告1. 运行 pytest2. 生成覆盖率报告3. 分析失败的测试4. 提供修复建议Claude Code 执行[Shell]: pytest tests/-v--covapp --cov-reportterm-missing --cov-reporthtml 分析测试结果 ✓45个测试通过 ✓ 覆盖率:87% ⚠3个测试跳过需要 Redis 建议1. 提高 routers/notes.py 的覆盖率当前78%2. 为 utils/validators.py 添加测试3. 添加并发测试场景四、代码审查与质量保障4.1 配置自动化代码审查使用 Claude Code 配置审查流程配置自动化代码审查1. 创建代码审查检查清单2. 配置自动审查脚本3. 集成到 Git hooks4. 生成审查报告模板生成的检查清单.cursor/code-review-checklist.md# 代码审查检查清单 ## 功能性检查 - [ ] 代码是否实现了预期功能 - [ ] 边界条件是否正确处理 - [ ] 错误处理是否完善 - [ ] 日志记录是否适当 ## 代码规范 - [ ] 遵循 PEP8 规范 - [ ] 命名清晰有意义 - [ ] 函数长度合理50 行 - [ ] 类职责单一 ## 类型安全 - [ ] 所有函数有类型注解 - [ ] 复杂类型使用 TypeVar/Generic - [ ] Optional/Union 使用正确 - [ ] mypy 检查通过 ## 安全性 - [ ] 无 SQL 注入风险 - [ ] 无 XSS 漏洞 - [ ] 敏感信息不硬编码 - [ ] 输入验证完善 ## 性能 - [ ] 无 N1 查询问题 - [ ] 大数据集使用分页 - [ ] 缓存使用合理 - [ ] 无内存泄漏风险 ## 测试 - [ ] 单元测试覆盖核心逻辑 - [ ] 边界情况有测试 - [ ] 错误路径有测试 - [ ] 测试可重复运行4.2 批量代码审查审查整个项目的代码批量审查 src/ 目录下的所有 Python 文件1. 检查代码规范PEP82. 检查类型注解完整性3. 检查安全漏洞4. 检查性能问题5. 生成审查报告 使用 Sub Agent 并行审查 - Agent1: 审查 models/ - Agent2: 审查 routers/ - Agent3: 审查 services/ - Agent4: 审查 utils/生成的审查报告# 代码审查报告 生成时间: 2024-XX-XX 审查范围: src/ 审查标准: PEP8, mypy, security, performance ## 总体评分 | 模块 | 规范 | 类型 | 安全 | 性能 | 综合 | |------|------|------|------|------|------| | models | 95 | 90 | 100 | 95 | 95 | | routers | 85 | 80 | 90 | 85 | 85 | | services | 90 | 85 | 95 | 80 | 87 | | utils | 92 | 88 | 100 | 90 | 92 | ## 发现的问题 ### 高优先级 (必须修复) 1. **src/routers/notes.py:45** - SQL 注入风险 python # 问题代码 query fSELECT * FROM notes WHERE title LIKE %{keyword}% # 建议修复 query SELECT * FROM notes WHERE title LIKE :keyword result await db.execute(query, {keyword: f%{keyword}%})src/services/auth.py:32- 密码明文存储# 问题代码user.passwordpassword# 明文存储# 建议修复user.hashed_passwordget_password_hash(password)中优先级 (建议修复)src/routers/users.py- 缺少错误处理建议添加 try-except 块统一错误响应格式src/services/note_service.py- N1 查询建议使用 joinedload 优化查询低优先级 (可选优化)部分函数缺少文档字符串部分变量命名可以更有意义修复建议运行black src/自动格式化运行mypy src/检查类型添加 bandit 安全检查到 CI为所有 API 路由添加限速### 4.3 自动化质量门禁 **配置 CI 质量门禁** bash 生成 CI/CD 配置 创建 .github/workflows/quality.yml包含 1. 代码格式检查black, isort 2. 代码规范检查flake8 3. 类型检查mypy 4. 安全检查bandit 5. 单元测试pytest 6. 覆盖率检查80%生成的 GitHub Actions 配置# .github/workflows/quality.ymlname:Code Qualityon:push:branches:[main,develop]pull_request:branches:[main]jobs:quality:runs-on:ubuntu-lateststeps:-uses:actions/checkoutv3-name:Set up Pythonuses:actions/setup-pythonv4with:python-version:3.9-name:Install dependenciesrun:|pip install -r requirements.txt pip install -r requirements-dev.txt-name:Check code formattingrun:|black --check src/ tests/ isort --check-only src/ tests/-name:Lint with flake8run:|flake8 src/ tests/ --max-line-length100-name:Type check with mypyrun:|mypy src/-name:Security check with banditrun:|bandit -r src/ -f json -o bandit-report.json || true-name:Test with pytestrun:|pytest tests/ -v --covsrc --cov-reportxml-name:Upload coverageuses:codecov/codecov-actionv3with:file:./coverage.xmlfail_ci_if_error:true五、完整项目流程示例5.1 项目启动到交付# Week 1: 项目规划创建项目结构生成架构文档生成任务清单# Week 2-3: 开发阶段并行开发用户模块并行开发笔记模块生成单元测试# Week 4: 测试与审查运行所有测试批量代码审查修复问题# Week 5: 文档与交付生成 API 文档生成部署文档创建 README5.2 实际开发会话示例# 会话1项目初始化初始化 FastAPI 项目 notes-app 包含完整目录结构、Docker 配置、CI/CD# 会话2需求分析分析需求在线笔记应用 生成功能清单、用户故事、技术方案# 会话3数据库设计设计数据库模型 - User, Note, Folder, Tag, Share 生成 SQLAlchemy 模型和迁移脚本# 会话4API 开发并行生成 API 路由 - Auth, Notes, Folders, Tags 包含完整的 CRUD 和权限控制# 会话5测试生成生成完整的测试套件运行测试并修复问题# 会话6代码审查审查所有源代码生成审查报告修复发现的问题# 会话7文档生成生成技术文档生成 API 文档完善 README# 会话8部署准备生成部署配置生成 Docker Compose创建部署文档六、最佳实践总结6.1 项目规划最佳实践分阶段交付每个阶段产出可验证的成果文档先行架构文档、API 文档先于代码任务明确每个任务有清晰的输入输出定义风险评估提前识别技术难点和风险点6.2 测试最佳实践测试先行核心功能先写测试再实现分层测试单元 → 集成 → E2E数据工厂使用工厂模式生成测试数据覆盖率目标核心代码 90%总代码 80%6.3 代码审查最佳实践自动化优先CI 中集成代码检查分层审查AI 初筛 → 人工深度审查问题分级高/中/低优先级修复跟踪确保所有高优先级问题修复七、Claude Code vs Cursor 对比阶段Claude Code 优势Cursor 优势项目规划CLI 快速生成文档Chat 可视化讨论开发实现批量文件操作多文件可视化编辑测试Sub Agent 批量生成单文件 Inline Edit代码审查Sub Agent 批量审查单文件深度 Review