CatoCut

A practical guide to writing agent specs that work. Patterns from 200+ production specs.

The Anatomy of a Spec

Five sections. Skip any one and you lose reliability.

spec:
  goal: "What the agent should accomplish"
  context: "What the agent needs to know"
  constraints: "What the agent must not do"
  output: "What the result should look like"
  verification: "How we know it worked"

Step 1: Write the Goal

One sentence. If you need two, you need two specs.

Bad: "Help with the codebase" / "Refactor auth and update tests and deploy"

Good: "Extract inline SQL in UserRepository into parameterized prepared statements"

Test: can you verify completion with yes/no? If not, sharpen it.

Step 2: Provide Context

Not "everything the agent might need." The minimum information required without asking questions.

context:
  repository: "payments-service"
  files_in_scope:
    - "src/repositories/UserRepository.ts"
  relevant_patterns:
    - "Repositories use DatabaseClient from src/db/client.ts"
    - "Parameterized queries: client.query(sql, params)"
  technical_constraints:
    - "TypeScript strict mode"
    - "No ORM — raw SQL only"

Step 3: Define Constraints

The most important section. Three types:

Boundary constraints

do_not_modify: ["src/db/client.ts", "src/migrations/*"]
do_not_change: ["Public API signatures", "Database schema"]

Behavioral constraints

behavior:
  - "Each change in a separate commit"
  - "All tests pass after each commit"
  - "No new dependencies"

Quality constraints

quality:
  - "All new code has type annotations"
  - "No any types"
  - "SQL uses parameterized values, never concatenation"

Step 4: Specify Output

Don't leave format to chance:

output:
  format: "git-patch"
  structure:
    - commit_message: "Conventional Commits format"
    - files_changed: "List with summary"
    - test_results: "Full output"

Step 5: Define Verification

verification:
  automated:
    - "TypeScript compiles with zero errors"
    - "All tests pass"
    - "No new 'any' types"
  manual:
    - "Review each commit for semantic correctness"

Common Mistakes

Implicit constraints — If you don't say "don't delete files," the agent might.
Overloaded goals — "And" in the goal = split the spec.
Missing context — Make implicit knowledge explicit.
No verification — "I'll review manually" is not verification.

Template

spec:
  goal: "[one sentence]"
  context:
    repository: ""
    files_in_scope: []
    relevant_patterns: []
  constraints:
    boundaries: []
    behavior: []
    quality: []
  output:
    format: ""
    structure: []
  verification:
    automated: []
    manual: []

"A well-written spec is a contract. A poorly-written spec is a wish."