Agentic Engineering Principles

Covers the agent-offloading principle for AI-assisted development — offload everything deterministic (git operations, validation commands, iteration accounting, output parsing, message routing) from the agent onto code, and reserve the agent for judgment, language understanding, and code synthesis. Includes the division-of-labor table, decision heuristics, orchestrator-owned fields, and typed side channels for agent-produced artifacts. Use when designing an agent workflow or orchestration loop, deciding whether a check belongs in a script or a prompt, tempted to ask an agent to track its own iterations or decide when to halt, or when parsing structured data out of agent response text.

Make a tool's deliberate constraints legible to agents — one-line rationale at the point of refusal, mechanisms stated where a wrong inference is invited, both sides of a ledger reported, and a published taxonomy of which friction is the product versus which is a defect. Use when agents work around or lobby against a constraint you intend to keep, when a tool refuses actions without saying why, when agents avoid a permitted action they have mis-priced, when designing refusal and status output, or when deciding what an agent should report as a bug versus absorb as the design.

Define a three-tier feedback vocabulary — hint, reminders, instruction — for steering agents from tool output, with strict tier contracts and an evidence-gated admission rule for reminders. Use when designing tool output that guides agents, adding hints or reminders to a CLI or tool, deciding where mid-flow guidance belongs, or reviewing whether guidance text is in the right tier.

Run structured retrospectives on any agent setup — instructions (AGENTS.md, CLAUDE.md, system prompts), skills, slash commands, workflows, processes, and tooling — after real use, mining finished runs for durable improvements. Covers the quality → cost → speed review order, deterministic extraction before judgment, spot-checking agent self-reports, and routing every finding to a concrete owner. Use when asked for a "retrospective on how the agent did", "post-mortem on this run", "improve my CLAUDE.md from this session", "audit how the workflow performed", or after rolling out new instructions, skills, or tooling and wanting to know what to change.

Design a purpose-built project CLI as the primary tool surface for AI coding agents, instead of in-process tool or MCP servers. Covers text-by- default output with opt-in --json (format follows the consumer), the exit- code taxonomy, structured errors, file-based payloads with a validate verb, preflight verbs for gated transitions with findings named by the transition they block, job-shaped long operations, identity resolution, a doctor self-check, and build-parity stamps. Use when building a CLI for agents, migrating away from in-process tool servers, designing tool output and error contracts, deciding between text and JSON output for an agent- facing tool, designing a lint or check command that runs ahead of a gate, choosing severity levels for findings, or deciding how agents should invoke project actions.

Applies an evidence-earned discipline to agent-facing documentation — a durable rule is written down only after it has bitten, and historical rationale lives in a dated lessons log rather than in code comments. Also covers instruction architecture: a small tool-agnostic root contract plus read-on-demand reference docs treated as persistent project memory with a drift-sync lifecycle. Use when setting up AGENTS.md or CLAUDE.md, when an instruction file keeps growing, when starting a lessons file such as PERFORMANCE.md, when deciding whether a rule has earned a place in agent guidance, or when agents appear to ignore instructions because the document is full of speculative advice.

Converts recurring "please don't" guidance into structural enforcement agents cannot drift past — deleting the foot-gun API, making illegal states unrepresentable in types, shrink-only ratchets, coverage assertions, checked-in budgets, declare-or-fail registries, derived artifacts, and round-trip contract tests. Use when agents keep reintroducing a pattern you documented against, when asking how to make a convention stick, when planning a migration off a legacy API, when a wrapping or registration convention has silently drifted, or when code review is the only thing standing between the codebase and a defect class.

Covers how to get reliable machine-readable output from AI agents — separate the thinking turn from the formatting turn, keep schemas flat and bounded, offload substantive content to files and return a small manifest, inject orchestrator-owned fields after parsing, and validate the manifest and the referenced files at the boundary. Includes schema design do/don't lists, prompting rules, the failure model, layered extraction, and one bounded repair turn. Use when an agent's JSON response drives workflow state, when designing a response schema or JSON Schema/Zod contract for an agent, when structured output keeps failing validation, or when deciding what belongs in JSON versus in a generated file.

Covers configuring development tooling — linters, type checkers, test runners, formatters — so AI agents can consume their output efficiently: keep success output O(1) rather than O(n), preserve every failure detail, strip colors, bail early, and truncate huge diffs. Includes tool-by-tool flags and config for ESLint, TypeScript, Vitest, Jest, and Prettier, the `:ai` package script convention, and a backend-neutral `AI_OUTPUT=1` switch. Use when an agent burns context on passing-test noise, when setting up pre-commit hooks or agent-invoked check commands, when asked to "make the test output quieter for the agent", when deciding what a command should print on success, or when configuring a project's lint/typecheck/test scripts for agent use.

Design progressive disclosure for the data agent-facing query commands return — bounded summary/outline defaults with stable zoom-in handles, explicit omission lines naming the exact follow-up command, and an escalation ladder from counts to scoped detail to file spillover. Includes a pattern menu (detail levels, field selection, filtering, pagination, search, ranked aggregation, sampling, delta output) and how query output doubles as an instruction surface. Use when designing list/show/search/status verbs for an agent CLI, when a query command can return large output, when an agent burns context reading query results, or when choosing default output size and drill-down flags for a read command.

Verify features against the live running system — real user flows, real API and model calls, and durable backend state — before calling them done. Covers scratch-datastore isolation, evidence engineering with greppable markers, round-trip persistence checks, and the change classes that only break live. Use when asked to "verify it actually works", "test end to end", "confirm this works in the real app", or before declaring a feature complete on the strength of a green test suite.

Design structured logging that AI agents can actually debug from — a stable documented event vocabulary, ambient trace context, scoped routing with a global timeline, documented query gotchas, a bounded log-analysis CLI, and forensic per-run logs for long agent executions. Use when designing logging for a project agents will debug, when an agent cannot find what it needs in the logs, when building an agent-friendly log query or performance-analysis tool, or when adding observability to multi-step agent runs.

Structure a CLI or tool surface as a progressive-disclosure graph where every subcommand's --help is a self-contained mini-skill, and derive every guidance surface from one typed registry so documentation drift becomes structurally impossible. Use when writing --help text, designing tool help systems, organizing command documentation for agents, or fighting drift between help text, parsers, and skill docs.