Skip to content

Banner image Banner image

Using AGENTS.md for Platform Engineering

Most platform incidents do not start with a complicated bug. They start with confusion.

One team follows one release path, another skips a check, and somebody quietly changes a naming rule without updating the docs. A few weeks later, nobody agrees on what "standard" means.

That is where AGENTS.md helps. It gives the team one shared playbook for planning, delivery, review, and release. Humans can follow it, and agents can follow it too.

The aim is straightforward: move changes from idea to production in a way that is calm, repeatable, and auditable.

Why AGENTS.md beats a wiki page

A wiki page gets out of date the moment the first person forgets to update it. AGENTS.md lives in the repo — it travels with the code, gets reviewed in PRs, and can be read by both humans and agents. The same file that guides your team guides Copilot and Claude Code.

Why AGENTS.md matters

Platform engineering gets expensive when every change follows a different path. AGENTS.md gives you a default path that people can trust.

In practice, it helps you:

  • Set clear scope before work starts
  • Keep delivery steps consistent across teams
  • Build quality checks into the workflow
  • Onboard new engineers faster
  • Let agents help without losing control

What to include in AGENTS.md

Keep it short and specific. If it reads like policy prose, people will ignore it.

These six parts are usually enough:

  1. Mission and scope
  2. Workflow steps
  3. Owners (human or agent)
  4. Quality gates
  5. Standards and conventions
  6. Output locations (docs, repos, diagrams)

Practical workflow for platform changes

Workflow overview Workflow overview AGENTS.md control plane container view AGENTS.md control plane container view

Use one repeatable flow for each meaningful platform change:

  1. Define
  2. Write the change goal, scope, and success criteria.
  3. Assess
  4. Capture current state, dependencies, and risks.
  5. Design
  6. Pick the approach and record trade-offs.
  7. Approve
  8. Confirm quality gates before implementation.
  9. Implement
  10. Make the change with tests and automation.
  11. Document
  12. Update runbooks, diagrams, and rollback steps.
  13. Validate
  14. Run operational checks in non-production first.
  15. Release
  16. Ship with owner sign-off and monitoring.

This sequence reduces rework because decisions are made early, before implementation starts to drift.

Agent collaboration flow

Agent collaboration flow Agent collaboration flow

AGENTS.md enforces one rule that matters: no phase moves forward without the required output from the previous phase. That single rule prevents a lot of avoidable regressions.

A minimal AGENTS.md you can copy

Start with this and adapt it:

# AGENTS.md

## Mission
- Keep platform delivery consistent and low risk

## Workflow
1. Plan → define scope, success criteria, risks
2. Survey → assess current state + gaps
3. Ideate → propose options + trade-offs
4. Review → approve approach + gates
5. Build → implement + automate
6. Document → runbooks + diagrams
7. Validate → operational review
8. Ship → release readiness

## Quality gates
- Every change has an owner
- Risks documented before build
- Docs updated before release

## Standards
- Naming: <team>-<service>-<env>
- Environments: dev → staging → prod
- Tooling: Helm + ArgoCD

If this reads like a checklist, that is intentional. Checklists are easier to follow when teams are busy or under pressure.

Practical examples

Each example maps directly to the workflow above.

1) Platform release checklist

  • Why: reduce release risk and keep gates consistent
  • What: release plan, rollback plan, communication checklist
  • How: run one fixed checklist and require sign-off at each gate

2) Incident runbook

  • Why: improve incident response speed and clarity
  • What: roles, steps, and post-mortem template
  • How: trigger the runbook and record actions as structured output

3) Infrastructure bootstrap

  • Why: create new environments without one-off setup work
  • What: baseline stack (ArgoCD, secrets, policies, monitoring)
  • How: define the exact bootstrap sequence in AGENTS.md

4) SLO review

  • Why: make reliability reviews repeatable
  • What: SLO attainment, regressions, and next actions
  • How: generate monthly SLO summaries from metrics

5) Sprint review deck (Marp)

  • Why: remove manual slide preparation
  • What: request volume, average handling time, top requester, top request type
  • How: use agents to populate a Marp deck from metrics scripts

Companion repo

Walkthroughs and scripts live here: https://github.com/polarpoint-io/ai-capabilities

How OpenClaw uses it (optional)

In OpenClaw, AGENTS.md acts as a shared source of truth for multiple agents. It defines:

  • Which agent handles each phase
  • The outputs required for each phase
  • The gates a lead agent must approve

This keeps multi-agent execution safe and predictable.

Common anti‑patterns

Avoid these mistakes:

The vague gate tell

"Review done" is not a quality gate. Neither is "approved." If someone has to ask what done means at 2am during an incident, the gate failed. Write gates as specific, verifiable conditions: "All readiness checks pass in staging" or "Rollback steps tested against previous image tag."

  • Too long: AGENTS.md should be a few screens, not a wiki
  • Vague gates: "review done" is not a gate - define what done means
  • No ownership: every phase needs a named owner
  • Stale rules: update it when tooling or workflows change

What you get

  • Predictable platform delivery
  • Lower operational risk
  • Faster onboarding
  • Consistent documentation
  • A workflow that scales as agent use grows

Apply this: start with the minimal template

Copy the minimal AGENTS.md template in this post verbatim. Run it for one sprint. You'll naturally identify what's missing from your specific context — team names, environment names, tooling specifics. Add those in. Don't try to write the perfect AGENTS.md upfront; iterate toward it.

Final note

AGENTS.md only works when teams treat it as part of delivery, not an afterthought. Keep it current, keep it short, and make it the first thing people check before they start work.

Frequently asked questions

How long should an AGENTS.md file be?

Short enough to read in under five minutes. If it runs beyond two or three screenfuls, split it: put the core workflow in AGENTS.md at the root, and push domain-specific detail into subdirectory AGENTS.md files. A 500-line AGENTS.md is a wiki page in disguise — nobody reads it under pressure.

Does AGENTS.md replace runbooks?

No. AGENTS.md defines the process — how changes move from idea to production. Runbooks define the procedure for specific operations: how to restart a service, how to rotate a secret, what to do when the database connection pool exhausts. Both belong in the repo; they answer different questions.

Can agents actually follow AGENTS.md without human help?

Yes, for well-defined, bounded tasks — querying metrics, updating diagrams, populating sprint review data. For anything involving judgment calls (is this risk acceptable? should we proceed?) the agent should pause and ask. The workflow in this post builds those confirmation gates in explicitly.

What's the difference between AGENTS.md and CLAUDE.md?

AGENTS.md is the open standard supported by VS Code Copilot, Cursor, and Claude Code (via import). CLAUDE.md is Anthropic's format, specific to Claude Code, with features like @path imports and .claude/rules/ for path-scoped overrides. Start with AGENTS.md for maximum portability; add a CLAUDE.md that imports it if you want Claude-specific features.

How do you keep AGENTS.md from going stale?

Treat it like production code. Every PR that changes a workflow, tool, or standard should include an AGENTS.md update if relevant. Add it to your PR template as a checkbox: "Does this change require an AGENTS.md update?" That single prompt catches most drift before it accumulates.