Issue 06 | Planning First: File-based Task Progress System — 🤝 Claude Code Teams Hands-on: Multi-Agent Parallel Development In-depth Guide

6.1 Planning with the planning-with-files Skill

Use the /planning-with-files skill for planning in the team-lead session:

Step 1: Brainstorming

Discuss the plan with Claude:

Which modules can run in parallel?
How will Agents collaborate?
What are the interface conventions?

Step 2: Writing Plans

Produce task_plan.md:

# Task Plan: Dual-Mode Web Calculator (Teams Parallel Solution)

## Parallel Architecture
┌─ ui-dev ──────────────┐  ┌─ logic-dev ─────────────┐
│ Phase A: HTML/CSS Skeleton │  │ Phase A: Calculation Engine Pure Functions │
│ Phase B: UI Interaction + a11y│  │ Phase B: Events + Persistence    │
└──────────┬─────────────┘  └──────────┬──────────────┘
           └────────┬──────────────────┘
                    ▼
        ┌─ qa-engineer ─────────┐
        │ Phase C: Unit + Integration Tests  │
        │ Phase D: E2E + Acceptance      │
        └───────────────────────┘

6.1.1 Planning File System

File	Purpose	When to Update
`task_plan.md`	Phases and Task Progress	At the start or completion of each task
`progress.md`	Session Log and Verification Evidence	After each meaningful work
`findings.md`	Technical Findings and Decisions	After each critical decision
`bugs.md`	Bug Log	Upon each discovery or fix

6.2 Testing Rules

6.2.1 TDD Cycle

RED → GREEN → REFACTOR → VERIFY Forbidden: Skipping RED, commenting out failed tests, weakening assertions to fake passes.

6.3 Git Rules

6.3.1 Commit Format

6.4 Security Boundaries

No backend, no API calls — pure client-side
localStorage only stores mode preferences, no sensitive data
No third-party scripts introduced

6.5 Project Structure

teamtest/ ├── CLAUDE.md ├── requirement.md ├── index.html ├── style.css ├── app.js └── .agents/workflows/

9.3 Analysis of CLAUDE.md Section Functions

Section	Function	Agent Behavior Impact
Project Overview	Helps Agent understand project context	Refers to technical constraints during decision-making
Tech Stack	Restricts tool selection	Will not introduce frameworks like React/Vue
Teams Development Mode	Defines division of labor and collaboration methods	Agent knows what it's responsible for and who to collaborate with
Collaboration Rules	Interface conventions	ui-dev reserves IDs, logic-dev binds using IDs
Skill Usage Rules	Enforces workflow order	Will not skip TDD and write code directly
Planning Files	State persistence standard	Uniformly uses [ ] [/] [x] to mark progress
Self-Governance Rules	Automatic decision boundaries	Stops after 5 failures, no infinite retries
Security Boundaries	Hard constraints	Does not introduce external scripts, does not call APIs

9.4 CLAUDE.md Writing Best Practices

flowchart LR
    subgraph "Must Include"
        A[Project Overview]
        B[Tech Stack Restrictions]
        C[Agent Division of Labor]
        D[Security Boundaries]
    end
    
    subgraph "Recommended Include"
        E[Skill Pipeline]
        F[Testing Rules]
        G[Self-Governance Rules]
        H[Planning File Format]
    end
    
    subgraph "Optional"
        I[Git Conventions]
        J[Plugin Usage Rules]
        K[Completion Rules]
    end

Principles:

Concise and Clear — Agents consuming CLAUDE.md also consume tokens; keep it under 300 lines
Use Tables and Lists — Easier to follow accurately than paragraphs
Write "What NOT to do" is more important than "What to do" — "Do not call Skill" > "Can call Skill"
Write Interface Conventions in Advance — Cross-Agent conventions like "reserve ID" must be in CLAUDE.md