Team Best Practices

Team Best Practices

How to use ai-coding-ok effectively in a team. Memory sharing, conflict resolution, PR reviews, and onboarding.

---

Sharing memory across the team

ai-coding-ok memory files live in .github/agent/memory/ — they're committed to git and shared automatically.

your-project/
├── .github/
│   └── agent/
│       └── memory/
│           ├── project-memory.md    ← Everyone sees the same architecture
│           ├── decisions-log.md     ← Everyone sees the same decisions
│           └── task-history.md      ← Everyone sees the same recent tasks

Setup for each team member

Each team member needs to install the ai-coding-ok skill once:

Claude Code users:

/plugin install ai-coding-ok@claude-plugins-official

Copilot users: No install needed — .github/copilot-instructions.md auto-loads.

Cursor users: No install needed — .cursor/rules/ai-coding-ok.mdc auto-loads.

The project files (.github/agent/, AGENTS.md, etc.) are already in the repo — no per-member setup needed beyond the skill installation.

---

New member onboarding

Step 1: They clone the repo

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

The project already has ai-coding-ok installed. Memory files are in the repo.

Step 2: They install the skill (one-time)

Claude Code: /plugin install ai-coding-ok@claude-plugins-official

Step 3: They ask for an overview

In Claude Code:

Read the project memory files and give me a 15-minute overview of the project.

The AI will:

• Summarize architecture from project-memory.md
• List key decisions from decisions-log.md
• Describe recent work from task-history.md

Step 4: They confirm understanding

Based on the memory, what are the top 3 constraints I should never violate?

This confirms the AI has correctly loaded the project context.

---

PR review checklist

When reviewing a PR from a teammate (or AI), check:

Memory updates

• task-history.md has a new entry for this PR
• The entry is accurate (matches what the PR actually does)
• If architecture changed, decisions-log.md has a new ADR
• If project facts changed, project-memory.md is updated

Code quality

• Tests are included
• Coding standards from coding-standards.md are followed
• No regression in unrelated features

Memory quality

• The task-history entry is informative (not just "fixed stuff")
• ADR entries have rationale, not just "chose X"
• No duplicate or contradictory entries

---

Handling memory conflicts

Scenario 1: Two team members add tasks simultaneously

Alice: TASK-050 in her branch
Bob:   TASK-050 in his branch (same number)

Solution: The task numbering is not critical. On merge:

1. Accept both entries
2. Renumber one to TASK-051
3. The content matters more than the number

Scenario 2: Conflicting architecture decisions

Alice: ADR-010: Use PostgreSQL
Bob:   ADR-010: Use MongoDB (different decision, same number)

Solution:

1. Discuss and resolve the actual decision
2. Keep the winning ADR with the correct number
3. Move the losing ADR to "Deprecated" status with a note referencing the winner

Scenario 3: Merge conflict in project-memory.md

Alice: Added "payment service" module
Bob:   Added "notification service" module

Solution: Both are valid additions. Merge both. If they conflict structurally, resolve manually.

---

CI enforcement

memory-check.yml

The CI workflow runs on every PR and checks:

# .github/workflows/memory-check.yml
- Check: task-history.md was modified
- Check: no {{placeholders}} leaked
- Check: version markers are consistent

If it fails, the PR gets a comment:

⚠️ Memory check failed:
- task-history.md was not updated in this PR
- Please add a task-history entry for this change

Making CI checks required

In your GitHub repo settings:

1. Settings → Branches → Branch protection rules
2. Add rule for main (or your default branch)
3. Check "Require status checks to pass before merging"
4. Add memory-check to the list

This ensures no PR merges without a memory update.

---

Team conventions

Task-history entry format

Agree as a team on the format:

### [TASK-XXX] {verb} {what}

- **Date**: YYYY-MM-DD
- **Type**: feat | fix | refactor | chore | docs
- **Author**: {name or "AI"}
- **Summary**: One sentence on what and why
- **Files changed**: key files
- **Related**: TASK-XXX, ADR-XXX (if applicable)

ADR format

Follow the ADR template consistently:

### ADR-XXX: {decision title}

- **Date**: YYYY-MM-DD
- **Status**: ✅ Accepted | ❌ Deprecated | 🔄 Superseded
- **Decision maker**: {name or "team consensus"}

#### Background
...

#### Options

| Option | Pros | Cons |
|--------|------|------|

#### Decision
...

#### Rationale
...

#### Impact
...

When to write an ADR

Write an ADR when:

• Choosing between technologies (database, framework, library)
• Making a significant architecture change
• Introducing a new pattern or convention
• Deprecating an old approach

Don't write an ADR for:

• Routine implementation choices
• Bug fixes
• Minor refactors

---

Rotating memory maintainer

For larger teams, designate a "memory maintainer" each week:

Responsibilities:

1. Scan task-history.md for quality (are entries informative?)
2. Check project-memory.md for staleness
3. Archive old task-history entries if >30
4. Propose deprecated ADRs for archival

This prevents memory rot without burdening any single person.

---

Offboarding

When a team member leaves:

1. No special action needed — memory files are in git
2. Their ADRs and task entries are part of the project history
3. If they were the primary author of certain modules, add a note to project-memory.md:

   ## 👤 Module Ownership
   | Module | Primary | Backup |
   |--------|---------|--------|
   | payment/ | (was: Alice) → Bob | Carol |

---

Multi-repo teams

If your team works across multiple repositories:

Option 1: Independent memory per repo

Each repo has its own ai-coding-ok installation. Memory is repo-scoped.

Option 2: Shared memory for monorepo

In a monorepo, one ai-coding-ok installation at the root covers all packages. Each package can have its own section in project-memory.md.

Option 3: Cross-repo ADR sharing

For decisions that span repos, create a shared docs/adr/ directory in one repo and link from others:

# In decisions-log.md
See ADR-005 (shared): [API versioning strategy](https://github.com/team/shared-docs/blob/main/adr/005-api-versioning.md)

---

Next steps

• Daily Workflow — individual workflow patterns
• CI Integration — setting up automated memory checks
• Customization Guide — standardizing customizations for the team