Design patterns for building reliable AI agents by moving deterministic work from the LLM to code.
Your agent works. Until it doesn't. And you can't tell why.
The LLM picks the wrong branch. It skips a step. It hallucinates a field name. You can't write a test for any of it because the decision happened inside a black box.
Code-First Agents is a set of patterns for moving decision-making out of the LLM and into deterministic code. The LLM orchestrates. Code executes. The more you push into code, the less you depend on probabilistic output for things that should be deterministic.
| Pattern | Description |
|---|---|
| Deterministic Tools | How to build CLI tools that do deterministic work and output JSON. The tool contract, the output spectrum, and progressive examples. |
| Skill Orchestration | How to write SKILL.md files that consume tool output. The LLM as executor, chaining tools, guards, and the verbatim execution principle. |
For the formal specification of both patterns, including the contract, trade-offs, reference implementations, and evolution history, see specs/code-first-agents.md.
Tools exist on a spectrum based on how much decision-making they absorb from the LLM:
| Level | Tool returns | LLM does | Example |
|---|---|---|---|
| 1. Data | Structured facts | Interprets, decides | get-issue-signals.ts |
| 2. Classification | Data + classification | Reads the class, branches | classify-issue.ts |
| 3. Instructions | Literal procedure | Executes verbatim | analyze-issue.ts |
At Level 3, the tool becomes a prompt factory. The LLM is a pure executor.
The examples/ directory contains a complete GitHub issue planning workflow that demonstrates the three levels. All tools run with Bun:
# Level 1: raw signals from the issue body
bun examples/tools/get-issue-signals.ts --owner acme --repo app --issue 42
# Level 2: deterministic classification
bun examples/tools/classify-issue.ts --owner acme --repo app --issue 42
# Level 3: complete planning procedure
bun examples/tools/analyze-issue.ts --owner acme --repo app --issue 42See examples/skills/plan-issue/SKILL.md for a full skill that orchestrates analyze-issue.ts at Level 3.
The full documentation lives at https://beogip.github.io/code-first-agents/.
The site source (HTML, CSS, markdown mirrors) lives in the gh-pages branch. This branch (main) holds the example tools, the example skill, and the repo metadata.
See CONTRIBUTING.md for guidelines on proposing new patterns and adding examples.
Built by Juan Gipponi.