Team Best Practices

团队最佳实践

如何在团队中有效使用 ai-coding-ok。记忆共享、冲突解决、PR 审查和新人入职。

---

在团队中共享记忆

ai-coding-ok 记忆文件位于 .github/agent/memory/——它们随 git 提交，自动共享。

your-project/
├── .github/
│   └── agent/
│       └── memory/
│           ├── project-memory.md    ← 所有人看到相同的架构
│           ├── decisions-log.md     ← 所有人看到相同的决策
│           └── task-history.md      ← 所有人看到相同的近期任务

每个团队成员的设置

每个成员需要安装一次 ai-coding-ok 技能：

Claude Code 用户：

bash ~/ai-coding-ok/install.sh --claude-code

Copilot 用户： 无需安装——.github/copilot-instructions.md 自动加载。

Cursor 用户： 无需安装——.cursor/rules/ai-coding-ok.mdc 自动加载。

---

新人入职流程

第 1 步：Clone 仓库

git clone git@github.com:team/your-project.git
cd your-project

项目已有 ai-coding-ok。记忆文件在仓库中。

第 2 步：安装技能（一次性）

Claude Code：bash ~/ai-coding-ok/install.sh --claude-code

第 3 步：请求概览

在 Claude Code 中：

读取项目记忆文件，给我一份 15 分钟的项目概览。

AI 会：

• 从 project-memory.md 总结架构
• 从 decisions-log.md 列举关键决策
• 从 task-history.md 描述近期工作

第 4 步：确认理解

根据记忆，我最不能违反的 3 条约束是什么？

确认 AI 正确加载了项目上下文。

---

PR 审查检查清单

审查队友（或 AI）的 PR 时，检查：

记忆更新

• task-history.md 有此 PR 的新条目
• 条目准确（与 PR 实际内容一致）
• 如果架构有变化，decisions-log.md 有新 ADR
• 如果项目事实有变化，project-memory.md 已更新

代码质量

• 包含测试
• 遵守 coding-standards.md 中的编码规范
• 无关联功能回归

记忆质量

• task-history 条目信息丰富（不是"修了点东西"）
• ADR 条目有理由，不只是"选了 X"
• 无重复或矛盾条目

---

处理记忆冲突

场景 1：两人同时添加任务

Alice：TASK-050 在她的分支
Bob：  TASK-050 在他的分支（相同编号）

解决： 任务编号不重要。合并时：

1. 接受两个条目
2. 将一个重编号为 TASK-051
3. 内容比编号更重要

场景 2：冲突的架构决策

Alice：ADR-010：使用 PostgreSQL
Bob：  ADR-010：使用 MongoDB（不同决策，相同编号）

解决：

1. 讨论并解决实际决策
2. 保留获胜的 ADR 使用正确编号
3. 将落败的 ADR 移到"已废弃"状态，标注引用获胜者

场景 3：project-memory.md 合并冲突

Alice：新增"支付服务"模块
Bob：  新增"通知服务"模块

解决： 两个都是有效新增。合并两者。如果结构冲突，手动解决。

---

CI 强制执行

memory-check.yml

CI 工作流在每次 PR 时运行，检查：

• task-history.md 是否被修改
• 无 {{占位符}} 泄漏
• 版本标记一致

如果失败，PR 收到评论：

⚠️ 记忆检查失败：
- task-history.md 未在此 PR 中更新
- 请为此变更添加 task-history 条目

设置 CI 强制检查

在 GitHub 仓库设置中：

1. Settings → Branches → Branch protection rules
2. 为 main 添加规则
3. 勾选"Require status checks to pass before merging"
4. 添加 memory-check

---

团队约定

任务历史条目格式

团队统一格式：

### [TASK-XXX] {动词} {什么}

- **日期**：YYYY-MM-DD
- **类型**：feat | fix | refactor | chore | docs
- **作者**：{姓名 或 "AI"}
- **摘要**：一句话说明做了什么以及为什么
- **变更文件**：关键文件
- **关联**：TASK-XXX、ADR-XXX（如适用）

何时写 ADR

写 ADR 的时机：

• 在技术之间做选择（数据库、框架、库）
• 做出重大架构变更
• 引入新模式或约定
• 废弃旧方法

不写 ADR 的时机：

• 常规实现选择
• Bug 修复
• 小重构

---

轮流记忆维护

大团队可指定每周的"记忆维护人"：

职责：

1. 扫描 task-history.md 质量（条目是否信息丰富？）
2. 检查 project-memory.md 是否过时
3. 归档超过 30 条的旧任务历史
4. 提议废弃的 ADR 归档

---

离职处理

团队成员离职时：

1. 无需特殊操作——记忆文件在 git 中
2. 他们的 ADR 和任务条目是项目历史的一部分
3. 如果他们是某些模块的主要作者，在 project-memory.md 中添加备注

---

下一步

• 日常开发流程 — 个人工作流模式
• CI 集成 — 设置自动化记忆检查
• 定制化指南 — 为团队标准化定制