team-coordination

チーム調整スキル

目的： チーム内の複数の Claude Code セッションが、競合を避けながら連携して作業できるようにします。共有状態、Todo の担当者割り当て、意思決定の同期、セッションの把握を管理します。

---

基本理念

┌─────────────────────────────────────────────────────────────────┐
│  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.                          │
└─────────────────────────────────────────────────────────────────┘

---

チーム状態の構成

プロジェクトが複数人での作業になったら、次の構成を作成します。

_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:

# Team State

*Last synced: [timestamp]*

## Active Sessions

| Contributor | Working On | Started | Files Touched | Status |
|-------------|------------|---------|---------------|--------|
| @alice | TODO-042: Add auth | 2024-01-15 10:30 | src/auth/* | 🟢 Active |
| @bob | TODO-038: Fix checkout | 2024-01-15 09:00 | src/cart/* | 🟡 Paused |
| - | - | - | - | - |

## Claimed Todos

| Todo | Claimed By | Since | ETA |
|------|------------|-------|-----|
| TODO-042 | @alice | 2024-01-15 | Today |
| TODO-038 | @bob | 2024-01-14 | Tomorrow |

## Recently Completed (Last 48h)

| Todo | Completed By | When | PR |
|------|--------------|------|-----|
| TODO-037 | @alice | 2024-01-14 | #123 |

## Conflicts to Watch

| Area | Contributors | Notes |
|------|--------------|-------|
| src/auth/* | @alice, @carol | Carol needs auth for TODO-045, coordinate |

## Announcements

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

---

コントリビューターファイル

_project_specs/team/contributors.md:

# Contributors

## Team Members

| Handle | Name | Focus Areas | Timezone | Status |
|--------|------|-------------|----------|--------|
| @alice | Alice Smith | Backend, Auth | EST | Active |
| @bob | Bob Jones | Frontend, Payments | PST | Active |
| @carol | Carol White | DevOps, Infra | GMT | Part-time |

## Ownership

| Area | Primary | Backup | Notes |
|------|---------|--------|-------|
| Authentication | @alice | @bob | All auth changes need @alice review |
| Payments | @bob | @alice | Stripe integration |
| Infrastructure | @carol | @alice | Deploy scripts, CI/CD |
| Database | @alice | @carol | Migrations need sign-off |

## Communication

- Slack: #project-name
- PRs: Always tag area owner for review
- Urgent: DM on Slack

## Working Hours Overlap

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

最も重なる時間帯：EST 午前9時～午後12時（3人全員）

---

ワークフロー

セッションの開始

┌─────────────────────────────────────────────────────────────────┐
│  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                                               │
└─────────────────────────────────────────────────────────────────┘

Todo の担当者割り当て

active.md に担当者の注記を追加します。

## [TODO-042] Add email validation

**Status:** in-progress
**Claimed:** @alice (2024-01-15 10:30 EST)
**ETA:** Today

...

作業中

• 新しいファイルに触れた場合は state.md を更新します
• アーキテクチャ上の選択を行う前に decisions.md を確認します
• 意思決定を行った場合は、すぐに decisions.md に追加します
• チームの同期を保つため、1～2時間ごとに状態の更新をプッシュします

セッションの終了

┌─────────────────────────────────────────────────────────────────┐
│  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                                             │
└─────────────────────────────────────────────────────────────────┘

引き継ぎの作成

別のチームメンバーに作業を引き継ぐ場合は、次のファイルを作成します。

_project_specs/team/handoffs/auth-feature-handoff.md:

# Handoff: Auth Feature (TODO-042)

**From:** @alice
**To:** @bob
**Date:** 2024-01-15

## Status

70% complete. Core auth flow works, need to add:
- [ ] Password reset flow
- [ ] Email verification

## What's Done

- Login/logout working
- JWT tokens implemented
- Session management done

## What's Left

1. Password reset - see src/auth/reset.ts (skeleton exists)
2. Email verification - need to integrate SendGrid

## Key Decisions Made

- Using JWT not sessions (see decisions.md)
- Tokens expire in 7 days
- Refresh tokens stored in 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

## 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

## Questions?

Slack me @alice if stuck

---

競合の防止

ファイル単位の状況把握

ファイルを変更する前に、state.md で誰がどのファイルを作業しているか確認します。

## Active Sessions

| Contributor | Working On | Started | Files Touched | Status |
|-------------|------------|---------|---------------|--------|
| @alice | TODO-042 | ... | src/auth/*, src/middleware/* | 🟢 Active |

src/auth/* に触れる必要があり、Alice がそこで作業している場合：

1. 実際に競合するか確認します（同じファイルか、同じ関数か）
2. 作業を進める前に Slack で調整します
3. 「注意すべき競合」セクションに注記を追加します

プッシュ前の確認

プッシュする前に、必ず次のことを行います。

git pull origin main
# Resolve any conflicts
git push

PR でのタグ付け

PR では、必ず担当領域のオーナーをタグ付けします。

## PR: Add password reset flow

Implements TODO-042

cc: @alice (auth owner), @bob (reviewer)

### Changes
- Added password reset endpoint
- Added email templates

### Testing
- [ ] Unit tests pass
- [ ] Manual testing done

---

意思決定の同期

意思決定を行う前に

1. 最新の decisions.md を取得します
2. その意思決定がすでに記録されているか確認します
3. 類似の意思決定がある場合は、それに従います（好みより一貫性を優先）
4. 新たな意思決定が必要な場合は、追加してすぐにプッシュします

意思決定の形式

## [2024-01-15] JWT vs Sessions for Auth (@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

---

コマンド

チームの状態を確認する

# See who's working on what
cat _project_specs/team/state.md

# Quick active sessions check
grep "🟢 Active" _project_specs/team/state.md

Todo の担当者を割り当てる

1. _project_specs/todos/active.md を編集します
2. Todo に担当者の注記を追加します
3. _project_specs/team/state.md を更新します
4. コミットしてプッシュします

担当者の割り当てを解除する

1. Todo から担当者の注記を削除します
2. state.md を更新します（担当者割り当て済み Todo から削除します）
3. コミットしてプッシュします

---

チーム向け Git フック

Pre-Push フックへの追加

pre-push にチーム状態の同期チェックを追加します。

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

# 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

---

Claude への指示

セッション開始時

チームプロジェクトでユーザーがセッションを開始した場合：

1. _project_specs/team/state.md があるか確認します

2. ファイルがある場合は読み込み、次の内容を報告します：

   • 現在アクティブなメンバー
   • 担当者が割り当てられている Todo
   • 注意すべき競合
   • 最近の告知

3. 何に取り組みたいか尋ねます

4. すでに担当者が割り当てられているか確認します

5. 担当者の割り当てと状態の更新を支援します

セッション中

• ファイルに触れる前に、他のメンバーがそこで作業していないか確認します
• 意思決定を行う前に、decisions.md を確認します
• ユーザーに定期的な状態の更新を促します

セッション終了時

• state.md の更新をユーザーに促します
• 引き継ぎを作成する必要があるか尋ねます
• 状態の変更をプッシュするよう促します

---

1 人開発から複数人開発への移行

プロジェクトでチーム調整が必要になった場合：

1. /check-contributors を実行します
2. _project_specs/team/ の構成を作成します
3. state.md と contributors.md を初期化します
4. 作業中の Todo に担当者の注記を追加します
5. CLAUDE.md を更新して、team-coordination.md スキルを参照するようにします

---

クイックリファレンス

ステータスアイコン

🟢 Active - Currently working
🟡 Paused - Stepped away, will return
🔴 Blocked - Needs help/waiting on something
⚪ Offline - Not working today

担当者割り当ての形式

**Claimed:** @handle (YYYY-MM-DD HH:MM TZ)

デイリースタンドアップのテンプレート

## Standup [DATE]

### @alice
- Yesterday: Finished TODO-042 auth flow
- Today: Starting TODO-045 password reset
- Blockers: None

### @bob
- Yesterday: Fixed checkout bug
- Today: Payment webhook integration
- Blockers: Need STRIPE_WEBHOOK_SECRET from @carol

---

チェックリスト

作業開始時

• git pull origin main
• team/state.md を読む
• Todo に担当者が割り当てられていないことを確認する
• active.md で Todo の担当者を割り当てる
• state.md を更新する
• 状態の変更をプッシュする

作業終了時

• すべての変更をコミットする
• current-state.md を更新する
• team/state.md を更新する
• 必要に応じて引き継ぎを作成する
• すべてをプッシュする