by yego | 2026-03-04 10:07:47+00:00
HOW AGENTS COORDINATE

Agents don't talk to each other directly. They coordinate through a shared docs repo:

docs/
├── tasks/ — task files per role (backend.md, frontend.md, ceo.md)
├── messages/ — inter-agent correspondence (dated markdown files)
├── decisions.md — architecture decision log
├── guidelines/ — coding conventions (Go, SQL, workflow)
├── reference/ — API spec, data model
└── tracking/ — workplan, sprint board

Task flow: CEO writes a task in docs/tasks/backend.md with objective, context, and acceptance criteria. Backend implements it, commits. If backend needs frontend changes, it writes a task in docs/tasks/frontend.md. Completed tasks get deleted — source of truth is the code, not task history. Important decisions get logged in decisions.md before deletion.

Messages: when agents need to discuss something, they write dated markdown files in docs/messages/. Messages get deleted once resolved — no accumulation.

Each agent has a /go skill — a custom Claude Code command that tells the agent to read its task file and messages inbox, then execute. I type /go, the agent picks up its tasks and works. But I review every output before the next step. Manual trigger, manual review, manual approval.

I also tried full auto-orchestration with watchexec — file changes trigger agents automatically, CEO creates tasks, agents pick them up on their own. I pushed it as a separate branch (https://github.com/yury-egorenkov/claude-code-docker/tree/mu...) but rolled back. Result: all agents stopped doing real work and started generating huge status reports for each other. The coordination overhead ate all the productivity. For now, manual control wins.

KEY RULES

After months of trial and error:

1. Separate git repos. /workspace/back/, /workspace/front/, /workspace/docs/ — each has its own .git. Never a monorepo.
2. Research before tasking. The #1 recurring mistake: an agent writes a task assuming something isn't implemented, when it already is. Rule: always read the actual code before creating tasks.
3. Small tasks only. Large tasks lead to large mistakes. Every task must be small enough to review in one pass.
4. Lessons learned file. docs/lessons-learned.md captures mistakes that keep recurring. Every agent reads it before starting. This file alone probably saved me more time than anything else.
5. No boundary crossing. Backend never touches HTML. Frontend never writes SQL. CEO never writes code.

WHY MARKDOWN OVER STRUCTURED TOOLS

I looked at task tracking tools designed for agents — JSONL-based, SQLite caching, dependency trees. But plain markdown: readable in any editor, diffs are clean in git, no extra tooling to install or break, and it serves as both coordination AND documentation.

Everyone's holding the same genie, but everyone's rubbing the lamp differently. Maybe the best approach doesn't exist yet.

THE DOCKER SETUP

Open-source: https://github.com/yury-egorenkov/claude-code-docker

- Network restrictions — iptables firewall allows only GitHub, npm, Anthropic APIs. No random outbound connections.
- Filesystem isolation — only workspace directory is mounted.
- State persistence — credentials and conversation history survive container restarts.
- Reproducible environment — Node.js, Go, Git, GitHub CLI, PostgreSQL client, all pre-installed.

WHAT I'D DO DIFFERENTLY

- Start with the docs repo and role constraints on day one. I added the coordination layer after hitting walls. Should have been the foundation from the start.
- Write the lessons-learned file immediately. Agents repeat the same mistakes across sessions.
- Never give an agent open-ended organizational authority. An agent with vague authority will build bureaucracy, not product.