Architecture your coding agent follows.
Layers, not spaghetti
A real shop app: 17 files, 33 imports. With a plan, every file gets a layer, and the one import that breaks it stands out.
As spaghetti, every import looks the same. Which one is wrong?
receipts.ts imports users.ts, but Shop may not use Auth.
As spaghetti, every import looks the same. Which one is wrong?
receipts.ts imports users.ts, but Shop may not use Auth.
From a plan to every pull request
Start from an idea or from code you already have. Planning takes a minute; after that it runs on every edit without you asking.
Measured on real Claude Code sessions
We gave Claude Code the same feature requests on the same app, with and without al dente, on Claude Haiku 4.5, Claude Sonnet 5.5, Claude Opus 5.5. None of the prompts mentions architecture.
Sessions that ended with code breaking the plan
One square per session, on the two tasks with a tempting shortcut.
- Ended breaking the plan
- Wrote the shortcut, fixed it in the same session
- Kept to the plan
Working alone, Claude never noticed its own shortcut: all 13 stayed in the final code. With al dente, 4 sessions wrote one, were stopped at that edit, and fixed it.
sessions that the guard blocked ended clean. Claude fixed the import itself, a median 7 s after the block. This is what it was told:
al-dente: src/shop/checkout.ts breaks the architecture agreed in al-dente.json.
line 6: imports "../auth/users.ts" from Auth, but Shop may only use: Data, Shared.to check an edit against the plan (median over 288 edits). Without al dente, a break waits for code review.
Catch it now, or pay for a second session
We sent every broken session back to Claude with the check's findings, as a code review would. All 13 of 13 came back clean, at 80,904 tokens and $0.063 each: almost as much as the feature itself.
- Without al dente, per feature
- 141,442
- tokens, $0.104, counting the follow-up
- With al dente, per feature
- 103,878
- tokens, $0.067: 27% fewer tokens, 35% lower cost
Where the tokens go
A normal Claude Code session next to one with al dente.
Knowing the plan
Claude Code alone: There's no plan: it works from the files it happens to read
With al dente: ~214 tokensonce, at session start
An edit that keeps to the plan
Claude Code alone: Nothing is checked
With al dente: 0 tokensthe check runs outside the model and says nothing
An edit that crosses the plan
Claude Code alone: 80,904 tokensfor the follow-up session that fixes it later, on average; until then it stays in the code
With al dente: ~101 tokensClaude is stopped at that edit and told the allowed way around it
Mapping code you already have (Apache Kafka, 3,819 source files)
Claude Code alone: ~468,000 tokensjust to read its import lines
With al dente: ~900 tokensone survey: its folders and the imports between them
83 valid runs of Claude Code (4 feature requests on a 16-file TypeScript app, 2 to 6 runs per model and setting; every feature checked in a real server and browser, 35 of 35 worked with al dente on). Small samples: read the rates as indicative. Per-feature totals are on the tasks with a tempting shortcut and assume each break is found and fixed in one follow-up session; tokens include cached input, as Claude Code reports them. The plan costs about 214 tokens at session start. Token sizes outside the sessions are characters divided by 4: the real hook on the demo app, and al-dente survey on Apache Kafka, whose source al dente checks (tests left out) is about 7,600,000 tokens. Method, raw results and the harness are on GitHub.
Why not a diagram or a linter
Diagram tools show a snapshot. Import linters check rules you wrote by hand, later. al dente sits in the loop with the agent.
| Capability | Diagram generators | Import linters | al dente |
|---|---|---|---|
| Rules come from a plan you pick in conversation | |||
| Checks each edit as the agent makes it, and tells the agent | |||
| Live map of the whole app | Snapshot | Static graph | |
| Pull request check |
Works with
It reads the code itself, with no compiler or language runtime to install.
Today
- TypeScript
- JavaScript
- Python
- Java
- Claude Code
- GitHub Actions
Coming next
- Kotlin
- C# and .NET
- Go
- Cursor
- Codex CLI
- Gemini CLI
Install
Two commands in Claude Code, then ask Claude for a plan.
Claude Code plugin
/plugin marketplace add Orest-Z/al-dente
/plugin install al-dente@al-denteThen, for a new app, ask Claude:
“Design the architecture for this app with al dente.”
Or, for code you already have:
“Map this project with al dente.”
For a new app it proposes two or three plans to pick from. For existing code it proposes parts from the imports already there, and older breaks never block. Either way, the guard starts on the next edit.
Pull request check
name: Architecture
on: pull_request
permissions:
contents: read
pull-requests: write
jobs:
al-dente:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: Orest-Z/al-dente@v1