agent-engineering

Agent Engineering

A durable decision framework for your own agent system. It exists because you will forget the reasoning behind past choices — this skill is the memory of how to decide, not a record of what you've already built.

The one rule that matters more than any mechanism

Do not build agent infrastructure because it sounds useful. Let a real, repeated problem determine what gets promoted, and promote the smallest thing that reliably solves it.

Every section below exists to serve that rule. If you're ever unsure, come back to this sentence before adding anything.

First questions, always: is there evidence, and has this recurred?

Before consulting anything else, ask:

• What's the actual evidence this is a problem — not a hunch, a single transcript, a diff.
• Did this happen more than once, or am I reacting to a single event?

Default: don't promote a one-off mistake. Just fix it and move on. If you catch yourself wanting to build something after one occurrence, that's the overengineering instinct — stop and just fix the thing.

Exceptions require a concrete reason, not a hunch — either:

• the cost of recurrence would be unacceptable even once (security, data loss, irreversible action), or
• the mechanism is genuinely cheap and strongly justified even for one occurrence (e.g. a one-line hard constraint that removes a whole class of mistake outright).

Continue below if the answer is "yes, this keeps happening," "I genuinely don't know, and not knowing is itself the problem" (→ Observability), or one of the exceptions above applies.

Relationship to self-improve

self-improve
    ↓
"I found a specific recurring mistake.
 How do I make this lesson durable?"
    → turns a confirmed recurring mistake into durable project
      knowledge — normally a rule in AGENTS.md, or an update to an
      appropriate skill.

agent-engineering (this skill)
    ↓
"What kind of agent-engineering mechanism
 should exist for this problem, if any?"
    → resolves to: nothing, a rule (→ hand to self-improve), a skill,
      a hard constraint, verification, an eval, an eval harness,
      observability, a feature map, or a trust/automation step.