Back to Details

team-coordination

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Team Coordination Skill

团队协作Skill

Load with: base.md
Purpose: Enable multiple Claude Code sessions across a team to coordinate and work together without conflicts. Manages shared state, todo claiming, decision syncing, and session awareness.
加载方式：base.md
用途： 支持团队内多个Claude Code会话无冲突地协作。管理共享状态、待办认领、决策同步和会话感知。

Core Philosophy

核心理念

┌─────────────────────────────────────────────────────────────────┐
│  TEAM CLAUDE CODE                                               │
│  ─────────────────────────────────────────────────────────────  │
│  Multiple devs, multiple Claude sessions, one codebase.         │
│  Coordination > Speed. Communication > Assumptions.             │
│                                                                 │
│  Before you start: Check who's working on what.                 │
│  Before you claim: Make sure nobody else has it.                │
│  Before you decide: Check if it's already decided.              │
│  Before you push: Pull and sync state.                          │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│  TEAM CLAUDE CODE                                               │
│  ─────────────────────────────────────────────────────────────  │
│  多人开发者，多个Claude会话，一个代码库。         │
│  协作＞速度。沟通＞假设。             │
│                                                                 │
│  开始前：查看谁在做什么。                 │
│  认领前：确保没人已认领。                │
│  决策前：检查是否已有决策。              │
│  推送前：拉取并同步状态。                          │
└─────────────────────────────────────────────────────────────────┘

Team State Structure

团队状态结构

When a project becomes multi-person, create this structure:
_project_specs/
├── team/
│   ├── state.md              # Who's working on what right now
│   ├── contributors.md       # Team members and their focus areas
│   └── handoffs/             # Notes when passing work to others
│       └── [feature]-handoff.md
├── session/
│   ├── current-state.md      # YOUR session state (personal)
│   ├── decisions.md          # SHARED - architectural decisions
│   └── code-landmarks.md     # SHARED - important code locations
└── todos/
    ├── active.md             # SHARED - with claim annotations
    ├── backlog.md            # SHARED
    └── completed.md          # SHARED
当项目变为多人协作时，创建以下结构：
_project_specs/
├── team/
│   ├── state.md              # 当前谁在做什么
│   ├── contributors.md       # 团队成员及其专注领域
│   └── handoffs/             # 工作交接说明
│       └── [feature]-handoff.md
├── session/
│   ├── current-state.md      # 你的个人会话状态
│   ├── decisions.md          # 共享 - 架构决策
│   └── code-landmarks.md     # 共享 - 重要代码位置
└── todos/
    ├── active.md             # 共享 - 包含认领标注
    ├── backlog.md            # 共享
    └── completed.md          # 共享

Team State File

团队状态文件

_project_specs/team/state.md
:
markdown
undefined
_project_specs/team/state.md
：
markdown
undefined

Team State

团队状态

Last synced: [timestamp]
最后同步时间：[时间戳]

Active Sessions

活跃会话

ContributorWorking OnStartedFiles TouchedStatus
@aliceTODO-042: Add auth2024-01-15 10:30src/auth/*🟢 Active
@bobTODO-038: Fix checkout2024-01-15 09:00src/cart/*🟡 Paused
-----
贡献者正在处理的工作开始时间涉及文件状态
@aliceTODO-042: 添加认证功能2024-01-15 10:30src/auth/*🟢 活跃
@bobTODO-038: 修复结账问题2024-01-15 09:00src/cart/*🟡 暂停
-----

Claimed Todos

已认领待办

TodoClaimed BySinceETA
TODO-042@alice2024-01-15Today
TODO-038@bob2024-01-14Tomorrow
待办事项认领人认领时间预计完成时间
TODO-042@alice2024-01-15今日
TODO-038@bob2024-01-14明日

Recently Completed (Last 48h)

近期完成（过去48小时）

TodoCompleted ByWhenPR
TODO-037@alice2024-01-14#123
待办事项完成人完成时间PR编号
TODO-037@alice2024-01-14#123

Conflicts to Watch

需要关注的冲突

AreaContributorsNotes
src/auth/*@alice, @carolCarol needs auth for TODO-045, coordinate
领域涉及贡献者说明
src/auth/*@alice, @carolCarol需要为TODO-045使用认证功能，需协调

Announcements

公告

  • [2024-01-15] @alice: Refactoring auth module, avoid touching until EOD
  • [2024-01-14] @bob: New env var required: STRIPE_WEBHOOK_SECRET

---
  • [2024-01-15] @alice: 正在重构认证模块，今日下班前请勿修改相关内容
  • [2024-01-14] @bob: 需要新增环境变量：STRIPE_WEBHOOK_SECRET

---

Contributors File

贡献者文件

_project_specs/team/contributors.md
:
markdown
undefined
_project_specs/team/contributors.md
：
markdown
undefined

Contributors

贡献者

Team Members

团队成员

HandleNameFocus AreasTimezoneStatus
@aliceAlice SmithBackend, AuthESTActive
@bobBob JonesFrontend, PaymentsPSTActive
@carolCarol WhiteDevOps, InfraGMTPart-time
标识姓名专注领域时区状态
@aliceAlice Smith后端、认证EST活跃
@bobBob Jones前端、支付PST活跃
@carolCarol WhiteDevOps、基础设施GMT兼职

Ownership

职责归属

AreaPrimaryBackupNotes
Authentication@alice@bobAll auth changes need @alice review
Payments@bob@aliceStripe integration
Infrastructure@carol@aliceDeploy scripts, CI/CD
Database@alice@carolMigrations need sign-off
领域主要负责人备份负责人说明
认证@alice@bob所有认证变更需经@alice审核
支付@bob@aliceStripe集成
基础设施@carol@alice部署脚本、CI/CD
数据库@alice@carol迁移需要签字确认

Communication

沟通方式

  • Slack: #project-name
  • PRs: Always tag area owner for review
  • Urgent: DM on Slack
  • Slack：#project-name
  • PR：务必标记领域负责人进行审核
  • 紧急情况：Slack直接私信

Working Hours Overlap

工作时间重叠

EST:  |████████████████████|
PST:  |   ████████████████████|
GMT:  |████████████|
      6am        12pm       6pm       12am EST

Best overlap: 9am-12pm EST (all three)

---
EST:  |████████████████████|
PST:  |   ████████████████████|
GMT:  |████████████|
      6am        12pm       6pm       12am EST

最佳重叠时间：EST时间9am-12pm（三人都在线）

---

Workflow

工作流程

Starting a Session

开始会话

┌─────────────────────────────────────────────────────────────────┐
│  START SESSION CHECKLIST                                        │
│  ─────────────────────────────────────────────────────────────  │
│  1. git pull origin main                                        │
│  2. Read _project_specs/team/state.md                           │
│  3. Check claimed todos - don't take what's claimed             │
│  4. Claim your todo in active.md                                │
│  5. Update state.md with your session                           │
│  6. Push state changes before starting work                     │
│  7. Start working                                               │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│  会话开始检查清单                                        │
│  ─────────────────────────────────────────────────────────────  │
│  1. git pull origin main                                        │
│  2. 阅读 _project_specs/team/state.md                           │
│  3. 检查已认领的待办事项 - 不要认领已被占有的             │
│  4. 在active.md中认领你的待办                                │
│  5. 在state.md中更新你的会话信息                           │
│  6. 开始工作前推送状态变更                     │
│  7. 开始工作                                               │
└─────────────────────────────────────────────────────────────────┘

Claiming a Todo

认领待办事项

In 
active.md
, add claim annotation:
markdown
undefined
在
active.md
中，添加认领标注：
markdown
undefined

[TODO-042] Add email validation

[TODO-042] 添加邮箱验证

Status: in-progress Claimed: @alice (2024-01-15 10:30 EST) ETA: Today
...
undefined
状态： 进行中 认领人： @alice (2024-01-15 10:30 EST) 预计完成时间： 今日
...
undefined

During Work

工作期间

  • Update 
    state.md
    if you touch new files
  • Check 
    decisions.md
    before making architectural choices
  • If you make a decision, add it to 
    decisions.md
    immediately
  • Push state updates every 1-2 hours (keeps team in sync)
  • 若修改新文件，更新state.md
  • 进行架构决策前查看decisions.md
  • 若做出决策，立即添加至decisions.md
  • 每1-2小时推送一次状态更新（保持团队同步）

Ending a Session

结束会话

┌─────────────────────────────────────────────────────────────────┐
│  END SESSION CHECKLIST                                          │
│  ─────────────────────────────────────────────────────────────  │
│  1. Commit your work (even if WIP)                              │
│  2. Update your current-state.md                                │
│  3. Update team state.md (status → Paused or Done)              │
│  4. If passing to someone: create handoff note                  │
│  5. Unclaim todo if abandoning                                  │
│  6. Push everything                                             │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│  会话结束检查清单                                          │
│  ─────────────────────────────────────────────────────────────  │
│  1. 提交工作内容（即使是未完成的）                              │
│  2. 更新你的current-state.md                                │
│  3. 更新团队state.md（状态→暂停或完成）              │
│  4. 若交接给他人：创建工作交接说明                  │
│  5. 若放弃任务，取消待办认领                                  │
│  6. 推送所有变更                                             │
└─────────────────────────────────────────────────────────────────┘

Creating a Handoff

创建工作交接

When passing work to another team member, create:
_project_specs/team/handoffs/auth-feature-handoff.md
:
markdown
undefined
当将工作交接给其他团队成员时，创建：
_project_specs/team/handoffs/auth-feature-handoff.md
：
markdown
undefined

Handoff: Auth Feature (TODO-042)

工作交接：认证功能（TODO-042）

From: @alice To: @bob Date: 2024-01-15
交接人： @alice 接收人： @bob 日期： 2024-01-15

Status

状态

70% complete. Core auth flow works, need to add:
  • Password reset flow
  • Email verification
完成70%。核心认证流程可用，需添加：
  • 密码重置流程
  • 邮箱验证

What's Done

已完成内容

  • Login/logout working
  • JWT tokens implemented
  • Session management done
  • 登录/登出功能正常
  • 已实现JWT令牌
  • 会话管理完成

What's Left

剩余工作

  1. Password reset - see src/auth/reset.ts (skeleton exists)
  2. Email verification - need to integrate SendGrid
  1. 密码重置 - 查看src/auth/reset.ts（已有框架）
  2. 邮箱验证 - 需要集成SendGrid

Key Decisions Made

已做出的关键决策

  • Using JWT not sessions (see decisions.md)
  • Tokens expire in 7 days
  • Refresh tokens stored in httpOnly cookies
  • 使用JWT而非会话（见decisions.md）
  • 令牌7天后过期
  • 刷新令牌存储在httpOnly cookies中

Watch Out For

需要注意的问题

  • The 
    validateToken
    function has a weird edge case with expired tokens
  • Don't touch 
    authMiddleware.ts
    - it's fragile rn
  • validateToken
    函数在处理过期令牌时有特殊边界情况
  • 不要修改
    authMiddleware.ts
    - 当前该文件不稳定

Files to Start With

起始文件

  1. src/auth/reset.ts - password reset
  2. src/email/verification.ts - email flow
  3. tests/auth.test.ts - add tests here
  1. src/auth/reset.ts - 密码重置
  2. src/email/verification.ts - 邮箱流程
  3. tests/auth.test.ts - 在此添加测试

Questions?

疑问？

Slack me @alice if stuck

---
遇到问题请在Slack上@alice

---

Conflict Prevention

冲突预防

File-Level Awareness

文件级感知

Before modifying a file, check state.md for who's touching what:
markdown
undefined
修改文件前，查看state.md中谁在处理相关内容：
markdown
undefined

Active Sessions

活跃会话

ContributorWorking OnStartedFiles TouchedStatus
@aliceTODO-042...src/auth/, src/middleware/🟢 Active

If you need to touch `src/auth/*` and Alice is working there:
1. Check if it's truly conflicting (same file? same functions?)
2. Coordinate via Slack before proceeding
3. Add a note to "Conflicts to Watch" section
贡献者正在处理的工作开始时间涉及文件状态
@aliceTODO-042...src/auth/, src/middleware/🟢 活跃

如果你需要修改`src/auth/*`且Alice正在处理该领域：
1. 检查是否真的存在冲突（同一文件？同一函数？）
2. 先通过Slack协调
3. 在"需要关注的冲突"部分添加说明

Pre-Push Check

推送前检查

Before pushing, always:
bash
git pull origin main
推送前，务必执行：
bash
git pull origin main

Resolve any conflicts

解决所有冲突

git push
undefined
git push
undefined

PR Tagging

PR标记

Always tag area owners in PRs:
markdown
undefined
PR中务必标记领域负责人：
markdown
undefined

PR: Add password reset flow

PR：添加密码重置流程

Implements TODO-042
cc: @alice (auth owner), @bob (reviewer)
实现TODO-042
抄送：@alice（认证负责人），@bob（审核人）

Changes

变更内容

  • Added password reset endpoint
  • Added email templates
  • 添加了密码重置端点
  • 添加了邮箱模板

Testing

测试

  • Unit tests pass
  • Manual testing done

---
  • 单元测试通过
  • 手动测试完成

---

Decision Syncing

决策同步

Before Making a Decision

决策前

  1. Pull latest 
    decisions.md
  2. Check if decision already exists
  3. If similar decision exists, follow it (consistency > preference)
  4. If new decision needed, add it and push immediately
  1. 拉取最新的
    decisions.md
  2. 检查是否已有相同决策
  3. 若存在类似决策，遵循该决策（一致性＞偏好）
  4. 若需要新决策，添加后立即推送

Decision Format

决策格式

markdown
undefined
markdown
undefined

[2024-01-15] JWT vs Sessions for Auth (@alice)

[2024-01-15] 认证使用JWT还是会话 (@alice)

Decision: Use JWT tokens Context: Need auth for API and mobile app Options:
  1. Sessions - simpler, server-side state
  2. JWT - stateless, works for mobile Choice: JWT Reasoning: Mobile app needs stateless auth, JWT works across platforms Trade-offs: Token revocation is harder, need refresh token strategy Approved by: @bob, @carol

---
决策： 使用JWT令牌 背景： API和移动应用需要认证 选项：
  1. 会话 - 更简单，服务端状态
  2. JWT - 无状态，适用于移动应用 选择： JWT 理由： 移动应用需要无状态认证，JWT跨平台可用 权衡： 令牌撤销更困难，需要刷新令牌策略 批准人： @bob, @carol

---

Commands

命令

Check Team State

查看团队状态

bash
undefined
bash
undefined

See who's working on what

查看谁在做什么

cat _project_specs/team/state.md
cat _project_specs/team/state.md

Quick active sessions check

快速查看活跃会话

grep "🟢 Active" _project_specs/team/state.md
undefined
grep "🟢 Active" _project_specs/team/state.md
undefined

Claim a Todo

认领待办

  1. Edit 
    _project_specs/todos/active.md
  2. Add claim annotation to todo
  3. Update 
    _project_specs/team/state.md
  4. Commit and push
  1. 编辑
    _project_specs/todos/active.md
  2. 为待办事项添加认领标注
  3. 更新
    _project_specs/team/state.md
  4. 提交并推送

Release a Claim

释放认领

  1. Remove claim annotation from todo
  2. Update state.md (remove from Claimed Todos)
  3. Commit and push
  1. 从待办事项中移除认领标注
  2. 更新state.md（从已认领待办中移除）
  3. 提交并推送

Git Hooks for Teams

团队Git钩子

Pre-Push Hook Addition

添加推送前钩子

Add team state sync check to pre-push:
bash
undefined
在推送前钩子中添加团队状态同步检查：
bash
undefined

In .git/hooks/pre-push (add to existing)

在.git/hooks/pre-push中添加（追加到现有内容）

Check if team state is current

检查团队状态是否为最新

echo "🔄 Checking team state..." git fetch origin main --quiet
LOCAL_STATE=$(git show HEAD:_project_specs/team/state.md 2>/dev/null | md5) REMOTE_STATE=$(git show origin/main:_project_specs/team/state.md 2>/dev/null | md5)
if [ "$LOCAL_STATE" != "$REMOTE_STATE" ]; then echo "⚠️ Team state has changed on remote!" echo " Run: git pull origin main" echo " Then check _project_specs/team/state.md for updates" # Warning only, don't block fi

---
echo "🔄 检查团队状态..." git fetch origin main --quiet
LOCAL_STATE=$(git show HEAD:_project_specs/team/state.md 2>/dev/null | md5) REMOTE_STATE=$(git show origin/main:_project_specs/team/state.md 2>/dev/null | md5)
if [ "$LOCAL_STATE" != "$REMOTE_STATE" ]; then echo "⚠️ 远程团队状态已变更！" echo " 执行：git pull origin main" echo " 然后查看_project_specs/team/state.md获取更新" # 仅警告，不阻止推送 fi

---

Claude Instructions

Claude指令

At Session Start

会话开始时

When user starts a session in a team project:
  1. Check for 
    _project_specs/team/state.md
  2. If exists, read it and report:
    • Who's currently active
    • What todos are claimed
    • Any conflicts to watch
    • Recent announcements
  3. Ask what they want to work on
  4. Check if it's already claimed
  5. Help them claim and update state
当用户在团队项目中开始会话时：
  1. 检查是否存在
    _project_specs/team/state.md
  2. 若存在，读取并报告：
    • 当前活跃的成员
    • 已认领的待办事项
    • 需要关注的冲突
    • 近期公告
  3. 询问用户想要处理的内容
  4. 检查该内容是否已被认领
  5. 帮助用户认领并更新状态

During Session

会话期间

  • Before touching files, check if someone else is working there
  • Before making decisions, check decisions.md
  • Remind user to update state periodically
  • 修改文件前，检查是否有其他人在处理相关内容
  • 决策前，查看decisions.md
  • 提醒用户定期更新状态

At Session End

会话结束时

  • Prompt user to update state.md
  • Ask if they need to create a handoff
  • Remind them to push state changes
  • 提示用户更新state.md
  • 询问是否需要创建工作交接说明
  • 提醒用户推送状态变更

Single → Multi-Person Conversion

单人→多人项目转换

When a project needs team coordination:
  1. Run 
    /check-contributors
  2. Create 
    _project_specs/team/
    structure
  3. Initialize 
    state.md
    and 
    contributors.md
  4. Add claim annotations to active todos
  5. Update CLAUDE.md to reference team-coordination.md skill
当项目需要团队协作时：
  1. 运行
    /check-contributors
  2. 创建
    _project_specs/team/
    结构
  3. 初始化
    state.md
    和
    contributors.md
  4. 为活跃待办事项添加认领标注
  5. 更新CLAUDE.md以引用team-coordination.md技能

Quick Reference

快速参考

Status Icons

状态图标

🟢 Active - Currently working
🟡 Paused - Stepped away, will return
🔴 Blocked - Needs help/waiting on something
⚪ Offline - Not working today
🟢 活跃 - 当前正在工作
🟡 暂停 - 暂时离开，会返回
🔴 阻塞 - 需要帮助/等待相关内容
⚪ 离线 - 今日不工作

Claim Format

认领格式

markdown
**Claimed:** @handle (YYYY-MM-DD HH:MM TZ)
markdown
**认领人：** @标识 (YYYY-MM-DD HH:MM 时区)

Daily Standup Template

每日站会模板

markdown
undefined
markdown
undefined

Standup [DATE]

站会 [日期]

@alice

@alice

  • Yesterday: Finished TODO-042 auth flow
  • Today: Starting TODO-045 password reset
  • Blockers: None
  • 昨日：完成TODO-042认证流程
  • 今日：开始处理TODO-045密码重置
  • 阻塞项：无

@bob

@bob

  • Yesterday: Fixed checkout bug
  • Today: Payment webhook integration
  • Blockers: Need STRIPE_WEBHOOK_SECRET from @carol

---
  • 昨日：修复结账bug
  • 今日：支付webhook集成
  • 阻塞项：需要从@carol获取STRIPE_WEBHOOK_SECRET

---

Checklist

检查清单

Starting Work

开始工作

  • git pull origin main
  • Read 
    team/state.md
  • Check todo not claimed
  • Claim todo in 
    active.md
  • Update 
    state.md
  • Push state changes
  • git pull origin main
  • 阅读
    team/state.md
  • 检查待办事项未被认领
  • 在
    active.md
    中认领待办
  • 更新
    state.md
  • 推送状态变更

Ending Work

结束工作

  • Commit all changes
  • Update 
    current-state.md
  • Update 
    team/state.md
  • Create handoff if needed
  • Push everything
  • 提交所有变更
  • 更新
    current-state.md
  • 更新
    team/state.md
  • 如有需要创建工作交接说明
  • 推送所有内容