Sample playbook for agent-first engineering

1. Project overview

Goal: A small but realistic “Agent‑maintained service”: a REST API for a Task Manager (users, projects, tasks) where:
- Agents build most features.
- Repo is structured for agent-first work.
- Background agents do “garbage collection” on code and docs. vercel
Stack (boring, well-known tools):
- Backend: Spring Boot 3.x → later upgrade path to 4.x.
- DB: Postgres.
- Frontend: React (optional, not required for the sample).
- CI: GitHub Actions.
- Agent: Claude / GPT-based coding agent integrated via IDE + repo instructions. news.ycombinator

You can swap Spring Boot for Node/Django etc. and keep the same structure.

2. Repo layout (agent‑first)

Top-level structure:

task-manager/
  AGENTS.md
  CLAUDE.md              # optional, tool-specific shim
  docs/
    index.md
    architecture.md
    domain-task-manager.md
    coding-standards.md
    agent-playbook.md
    patterns/
      spring-rest-patterns.md
      spring-data-patterns.md
      react-patterns.md
  plans/
    roadmap.md
    current-iteration.md
    tech-debt.md
  src/
    main/
      java/com/example/taskmanager/...
    test/
      java/com/example/taskmanager/...
  tools/
    garbage-collector/
      semantic_purge.py
    doc-gardener/
      doc_gardener.py
    linters/
      architecture_linter.py
  .github/workflows/
    ci.yml
    doc-gardener.yml
    garbage-collector.yml
  README.md

Key points:

AGENTS.md is a table of contents, ~100 lines, with pointers into docs/ and plans/, not a full manual. openai
All decisions, specs, and plans live inside the repo (docs/, plans/), never only in Slack / Google Docs. openai
Agents are expected to follow “progressive disclosure”: start with AGENTS.md, then dive deeper as linked. openai

3. Core instruction files

3.1 AGENTS.md (table of contents, ~100 lines)

Example skeleton (trim to your style):

# AGENTS.md – Agent Entry Point

You are working on the `task-manager` service: a Spring Boot REST API for managing users, projects, and tasks.

When starting any task, follow this sequence:

1. Read `docs/index.md` (project summary, directory map).
2. For backend tasks, read:
   - `docs/architecture.md`
   - `docs/domain-task-manager.md`
   - `docs/coding-standards.md`
   - `docs/patterns/spring-rest-patterns.md`
3. For frontend tasks, read:
   - `docs/patterns/react-patterns.md`

Plans and work status:

- Long-term roadmap: `plans/roadmap.md`
- Current sprint / iteration: `plans/current-iteration.md`
- Known tech debt and cleanup areas: `plans/tech-debt.md`

Quality and guardrails:

- Always add or update tests under `src/test/...` for any behavior change.
- Do not introduce new libraries without editing `docs/architecture.md` and explaining why.
- Prefer existing patterns shown in:
  - `docs/patterns/spring-rest-patterns.md`
  - `docs/patterns/spring-data-patterns.md`

When you get something wrong:

- Explain what repo capability or documentation was missing.
- Suggest where a new doc or rule should live (e.g., `docs/patterns/...`, `docs/coding-standards.md`).

If you are unsure:

- Ask the user which part of the repo to read next.

This matches the “AGENTS.md as navigational map, not encyclopedia” pattern. vercel

3.2 docs/ (system of record)

Example minimal docs:

docs/index.md
- One‑page summary of project purpose, tech stack, folder map. openai
docs/architecture.md
- Context, container, key components, and high‑level rules (e.g., controllers thin, services own logic; no DB access from controllers).
docs/domain-task-manager.md
- Entities (User, Project, Task), invariants, lifecycle rules.
docs/coding-standards.md
- Naming, logging, error handling, package structure, test strategy.
docs/patterns/spring-rest-patterns.md
- Example controller+service+repository pattern, standard error responses.
docs/patterns/spring-data-patterns.md
- How to use Spring Data, pagination, query patterns.

These are the “deeper docs” that AGENTS.md points to. vercel

3.3 plans/ (checked into repo)

plans/roadmap.md
- Q1/Q2 themes, big features, expected migrations (e.g., Spring Boot 4 later). openai
plans/current-iteration.md
- 5–10 concrete tasks with status (To‑do / In progress / Done).
plans/tech-debt.md
- File‑level or module‑level debt, how to fix, priority. This becomes input for cleanup agents. openai

Agents read these instead of Jira. openai

4. Development loop with the agent

Treat the agent like a junior dev:

Human creates/updates a plan item in plans/current-iteration.md.
Human writes or adjusts tests / high‑level spec in codebase (TDD where practical).
Agent is asked to implement or modify code only via the repo context and AGENTS.md.
Agent opens PR (or changeset) which:
- Follows patterns from docs/patterns/.
- Updates docs if behavior changed.
CI enforces style, tests, and architecture rules. openai

This matches the “progressive disclosure” recommendation and AGENTS.md usage model. vercel

5. Automated quality: CI, linters, garbage collectors

5.1 CI pipeline (.github/workflows/ci.yml)

Typical steps:

mvn test or ./gradlew test.
Run code format / lint (e.g., Spotless, Checkstyle).
Run tools/linters/architecture_linter.py to enforce repo rules (e.g., no direct DB in controllers). openai
Optionally run security scan (e.g., mvn verify with plugins).

OpenAI describe encoding “golden principles” as mechanical rules and enforcing via linters and scheduled cleanup. openai

5.2 Architecture linter (coaching, mechanical enforcement)

tools/linters/architecture_linter.py can:

Fail if:
- controller packages import repositories directly.
- New modules bypass shared utility packages defined in docs/architecture.md. openai
Produce human‑readable hints that agents see in CI logs (“Move DB access to a Service class, see docs/patterns/spring-rest-patterns.md”). openai

This makes linting into coaching for both humans and agents. openai

5.3 Garbage‑collector agent (code “entropy” control)

You implement a scheduled workflow: .github/workflows/garbage-collector.yml:

Runs nightly or weekly.
Invokes tools/garbage-collector/semantic_purge.py (or equivalent) to:
- Detect “patch” instructions that accumulated in AGENTS.md or docs (e.g., “ALWAYS return JSON field X”) and classify them as:
  - Syntax/Capability (high‑decay, purge on model upgrade).
  - Business/Context (keep). dev
- Suggest removal / consolidation of outdated patches.
Opens small PRs that:
- Remove or rewrite obsolete instructions.
- Simplify AGENTS.md back to ~100 lines. dev

This follows the “entropy and garbage collection” idea plus semantic purge for prompt rot. dev

5.4 Doc‑gardener agent (keep docs and code in sync)

Workflow: .github/workflows/doc-gardener.yml:

Runs nightly.
Steps:
- Use static analysis + LLM to compare:
  - Public REST endpoints in code vs documented endpoints in docs/domain-task-manager.md and docs/patterns/spring-rest-patterns.md.
  - Entity fields vs documented schema. reddit
- If mismatches found, open a PR which:
  - Updates docs to match code, or
  - Highlights unclear discrepancies in a TODO block.

OpenAI describe a recurring “doc‑gardening” agent that opens fix‑up PRs when docs drift. reddit

6. “When the agent screws up” loop

When the agent makes a bad change:

Do not just retry the same prompt.
Ask inside the PR or comment:
- “What capability was missing from this environment?”
- “Where should that capability or rule live in the repo?”
Use the answer to:
- Add/extend a doc under docs/ or docs/patterns/.
- Add or adjust an architecture rule or linter.
- Possibly add a small test pattern to guide future behavior.

Then the garbage‑collector / semantic purge ensures that only durable, generalisable lessons remain, while brittle one-off patches decay. dev

7. Concrete “Day 0 → Day 7” plan

Day 0–1: Skeleton and instructions

Create repo with:
- Basic Spring Boot app, one simple HealthController.
- AGENTS.md, docs/index.md, docs/architecture.md, docs/coding-standards.md, docs/domain-task-manager.md.
- plans/roadmap.md, plans/current-iteration.md, plans/tech-debt.md.
- CI workflow (tests + linters). vercel

Day 2–3: First features with agent

Define in plans/current-iteration.md:
- “Implement CRUD for Task with REST endpoints and basic validation.”
Ask the agent to:
- Read AGENTS.md → docs.
- Implement TaskController, TaskService, TaskRepository, entity, DTOs, tests.
- Update docs for endpoints. vercel

Day 4: Introduce automated linters

Implement architecture linter and wire it into CI. openai
Add a few “golden principles” as static checks (no direct DB in controllers, use shared utils, etc.). openai

Day 5: Garbage‑collector agent

Implement semantic_purge.py (or similar) over AGENTS.md:
- Classify instruction lines.
- Open PRs to remove outdated, syntax‑only patches on a schedule. dev
Add .github/workflows/garbage-collector.yml to run weekly and open PRs. dev

Day 6: Doc‑gardener agent

Implement doc_gardener.py to:
- Parse controllers/endpoints, compare with docs.
- Open PRs when mismatches detected. reddit
Add workflow .github/workflows/doc-gardener.yml to run nightly. openai

Day 7: Hardening and review

Review PRs from garbage collector and doc‑gardener, refine heuristics.
Tighten AGENTS.md back to ~100 lines, moving anything verbose into specific docs. vercel
Capture learnings in docs/agent-playbook.md so the system becomes self‑documenting.

8. How you’d actually use this with your agents

Configure your IDE tools (Cursor, Claude Code, Copilot, etc.) so that:
- They always load AGENTS.md into system context for this repo. news.ycombinator
- They treat docs/ as primary reference for architecture/domain questions. openai
Use one or more AGENTS.md files per package/module as the repo grows for more localized rules. news.ycombinator
When you start your Spring Boot 3 → 4 migration later, add:
- docs/spring-boot-4-migration.md.
- A new plan file plans/spring-boot-4-migration.md.
- Pointers in AGENTS.md under a new “Migrations” section. vercel

This gives you a full sample project pattern: structure, instructions, background agents, and concrete day‑by‑day steps aligned with the agent‑first playbook you quoted.

rsrini7/Agent‑maintained-service.md

Select an option

No results found