mirror of https://github.com/catlog22/Claude-Code-Workflow.git synced 2026-03-01 15:03:57 +08:00

Files

catlog22 c3ddf7e322 docs: add VitePress documentation site

- Add docs directory with VitePress configuration
- Add GitHub Actions workflow for docs build and deploy
- Support bilingual (English/Chinese) documentation
- Include search, custom theme, and responsive design

2026-02-28 16:14:09 +08:00

8.6 KiB

Raw Blame History

最佳实践

一句话定位

最佳实践是团队高效协作的保障 — 规范制定、代码审查、文档维护、团队协作的实践经验总结。

6.1 团队协作规范

6.1.1 角色职责定义

角色	职责	技能要求
Planner	需求分析、任务分解	架构思维、沟通能力
Developer	代码实现、单元测试	编码能力、测试意识
Reviewer	代码审查、质量把关	代码敏感度、规范理解
QA	质量保证、测试验证	测试设计、风险识别
Facilitator	协调沟通、进度跟踪	项目管理、冲突解决

6.1.2 工作流选择

场景	推荐工作流	理由
新功能开发	PlanEx	规划与执行分离，降低风险
Bug 修复	Lifecycle	完整闭环，确保修复质量
代码重构	IterDev	迭代改进，持续优化
技术决策	Brainstorm	多视角分析，全面考虑
Issue 管理	Issue	可追溯，易管理
UI 开发	UIDesign	设计到代码无缝衔接

6.1.3 沟通协议

消息格式

[<角色>] <操作> <对象>: <结果>

示例:
[Planner] 任务分解完成: 生成 5 个子任务
[Developer] 代码实现完成: user-auth.ts, 324 行
[Reviewer] 代码审查完成: 发现 2 个问题，建议 1 处优化

状态报告

状态	含义	后续动作
pending	待处理	等待依赖完成
in_progress	进行中	继续执行
completed	已完成	可以被依赖
blocked	被阻塞	需要人工介入

6.2 代码审查流程

6.2.1 审查维度

维度	检查项	严重性
正确性	逻辑正确、边界处理	HIGH
性能	算法效率、资源使用	MEDIUM
安全	注入漏洞、权限检查	HIGH
可维护性	代码清晰、模块化	MEDIUM
测试覆盖	单元测试、边界测试	MEDIUM
规范符合	编码规范、项目约定	LOW

6.2.2 审查流程

┌─────────┐   ┌─────────┐   ┌─────────┐   ┌─────────┐
│  提交   │──▶│  审查   │──▶│  反馈   │──▶│  修复   │
│ 代码    │   │ 代码    │   │ 意见    │   │ 问题    │
└─────────┘   └─────────┘   └─────────┘   └─────────┘
     │            │            │            │
     ▼            ▼            ▼            ▼
  Push PR      自动审查      人工审查      修复验证
  CI 检查      6 维度检查    代码走查      再次审查

6.2.3 审查清单

代码正确性

逻辑正确，无 bug
边界条件处理
错误处理完整
资源释放正确

性能

算法复杂度合理
无内存泄漏
无冗余计算
缓存策略合理

安全

无 SQL 注入
无 XSS 漏洞
权限检查完整
敏感数据保护

可维护性

命名清晰
模块化良好
注释充分
易于测试

测试覆盖

单元测试完整
边界测试覆盖
异常情况测试
集成测试验证

规范符合

编码风格统一
命名规范遵守
项目约定遵循
文档完整

6.2.4 反馈格式

## 审查结果

### 问题
1. **[HIGH]** SQL 注入风险
   - 位置: `src/auth/login.ts:45`
   - 建议: 使用参数化查询

2. **[MEDIUM]** 性能问题
   - 位置: `src/utils/cache.ts:78`
   - 建议: 使用 LRU 缓存

### 建议
1. 命名优化: `data` → `userData`
2. 模块拆分: 建议将 Auth 逻辑独立

### 通过条件
- [ ] 修复 HIGH 问题
- [ ] 考虑 MEDIUM 建议

6.3 文档维护策略

6.3.1 文档分类

类型	位置	更新频率	负责人
规范文档	`.workflow/specs/`	按需	架构师
参考文档	`docs/ref/`	每次变更	开发者
指南文档	`docs/guide/`	每月	技术写手
API 文档	`docs/api/`	自动生成	工具
FAQ	`docs/faq.md`	每周	支持团队

6.3.2 文档更新触发

事件	更新内容
新增功能	添加功能文档和 API 参考
规范变更	更新规范文档和迁移指南
Bug 修复	更新 FAQ 和已知问题
架构变更	更新架构文档和决策记录
代码审查	补充缺失的注释和文档

6.3.3 文档质量标准

标准	要求
准确性	与实际代码一致
完整性	覆盖所有公开 API
清晰性	易于理解，示例充分
时效性	及时更新，不滞后
可导航	结构清晰，易于查找

6.4 Memory 管理最佳实践

6.4.1 Memory 记录时机

时机	记录内容
架构决策	技术选型、设计决策
问题解决	Bug 根因、解决方案
经验总结	最佳实践、避坑指南
规范约定	编码规范、命名约定
已知问题	Bug、限制、TODO

6.4.2 Memory 格式规范

## [类型] 标题

### 背景
- **问题**: ...
- **影响**: ...
- **上下文**: ...

### 分析/决策
- **方案**: ...
- **理由**: ...
- **替代方案**: ...

### 结果
- **效果**: ...
- **数据**: ...

### 相关
- [相关记忆](memory-id)
- [相关代码](file-link)
- [相关文档](doc-link)

6.4.3 Memory 维护

维护项	频率	内容
去重	每周	合并重复记忆
更新	按需	更新过时内容
归档	每月	归档历史记忆
清理	每季度	删除无用记忆

6.5 Hook 使用规范

6.5.1 Hook 类型

Hook 类型	用途	示例
pre-command	注入规范、加载上下文	自动加载 CLAUDE.md
post-command	保存 Memory、更新索引	自动保存决策
pre-commit	代码审查、规范检查	自动运行 Lint
file-change	自动格式化、更新索引	自动格式化代码

6.5.2 Hook 配置原则

原则	说明
最小化	只配置必要的 Hook
幂等性	Hook 执行结果可重复
可恢复	Hook 失败不影响主流程
可观测	Hook 执行有日志记录

6.6 团队协作技巧

6.6.1 冲突解决

冲突类型	解决策略
规范冲突	团队讨论，统一规范
技术分歧	头脑风暴，数据驱动
进度冲突	优先级排序，资源调整
质量冲突	制定标准，自动化检查

6.6.2 知识共享

方式	频率	内容
技术分享	每周	新技术、最佳实践
代码走查	每次 PR	代码逻辑、设计思路
文档同步	每月	文档更新、规范变更
问题复盘	每次事故	根因分析、改进措施

6.6.3 效率提升

技巧	效果
模板化	复用成功模式
自动化	减少重复工作
工具化	提升开发效率
标准化	降低沟通成本

6.7 快速参考

工作流选择指南

场景	工作流	命令
新功能	PlanEx	`/workflow:plan`
Bug 修复	Lifecycle	`/unified-execute-with-file`
重构	IterDev	`/refactor-cycle`
决策	Brainstorm	`/brainstorm-with-file`
UI 开发	UIDesign	`/workflow:ui-design`

代码审查清单

正确性检查
性能检查
安全检查
可维护性检查
测试覆盖检查
规范符合检查

Memory 维护

操作	命令
列出记忆	`ccw memory list`
搜索记忆	`ccw memory search "..."`
导入记忆	`ccw memory import "..."`
导出记忆	`ccw memory export <id>`

总结

Claude_dms3 的最佳实践可以总结为：

规范先行 - 制定清晰的团队规范
流程保障 - 使用合适的工作流
质量把关 - 严格的代码审查
知识沉淀 - 持续维护 Memory 和文档
持续改进 - 定期复盘和优化

8.6 KiB Raw Blame History