agentleFS
Sign inStart free
anandartinanandartin/celestial-skills/skills/spec-before-code-engineering/AGENTS.md

celestial-skills / spec-before-code-engineering

AGENTS.md1 starsChanged 18 days agoApache-2.0View on GitHub

Write a one-page spec and a step plan before implementing, then build and check against it, so the work matches what was asked the first time. Generated from the Celestial engineering practice “Spec before code”.

The file

We split this AGENTS.md into the rules it gives an agent

4 rules. About 0 are common, 4 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈4

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Write a one-page spec and a step plan before implementing, then build and check against it, so the work matches what was asked the first …

    line 3
  2. Distinctive:

    Keep the spec to about one page.

    line 24
  3. Distinctive:

    Write acceptance criteria as observable behaviour, never as implementation steps.

    line 25
  4. Distinctive:

    Call out every schema, API contract or data migration in the approach section.

    line 26

≈ “Common” is an estimate: at least 1 in 5 of the 40,246 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

AGENTS.md — Spec before code

Write a one-page spec and a step plan before implementing, then build and check against it, so the work matches what was asked the first time.

How to do it

  1. State the problem — Write two or three sentences on who has the problem, what they cannot do today and why it matters now. Leave solutions out of this part.
  2. Define acceptance criteria — List the observable outcomes that mean done, each written so a test or a reviewer can check it. Include error and empty cases.
  3. Mark scope and non-goals — List what is in scope and, just as explicitly, what is out. Name any constraints: performance targets, compatibility, deadlines.
  4. Sketch the approach — Describe the design in a few paragraphs: modules touched, data changes, interfaces, and alternatives you rejected with one line each on why.
  5. Resolve open questions — List unknowns and get answers from the requester or owner before coding. Unanswered questions become explicit assumptions in the spec.
  6. Break it into steps — Split the work into ordered tasks that each end in a green build and a reviewable commit. Note which acceptance criterion each step satisfies.
  7. Build against the plan — Implement step by step, ticking tasks off. When reality differs from the plan, update the spec first, then the code.
  8. Verify against the spec — Before opening the pull request, walk every acceptance criterion and show evidence (test name, screenshot, preview link). Link the spec in the pull request.

Checklist (before a pull request)

  • The spec has a problem statement, acceptance criteria, non-goals and an approach
  • Every acceptance criterion is testable and has evidence attached
  • Open questions are answered or recorded as assumptions
  • The plan's steps are all complete or explicitly deferred
  • The spec was updated where the build departed from it
  • The pull request links the spec

Rules

  • Keep the spec to about one page; split the feature if it needs more. (Long specs go unread and hide the decisions that matter.)
  • Write acceptance criteria as observable behaviour, never as implementation steps. (Criteria tied to implementation cannot catch a wrong design.)
  • Call out every schema, API contract or data migration in the approach section. (These are the hardest changes to undo after release.)
  • Note who is allowed to do each new action and how that is enforced. (Authorisation decided during coding is often forgotten.)

Checks

GateToolThresholdWhen
Spec linkedPull request template checkPull requests over 200 changed lines link a spec with acceptance criteriaEvery pull request

Generated from the Celestial engineering practice “Spec before code”.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free