DEV Community: Alberto Arena

The Laravel schema nobody chose

Alberto Arena — Fri, 28 Aug 2026 11:16:10 +0000

Fifteen real Laravel applications, every one of them a codebase you can go and read. 811 tables. One pinned MySQL 8.0 database, migrations only, no seed data. Every application installed from a clean clone and migrated before a single table was read.

This is not a review of those fifteen projects. It is a census: a look at what a Laravel schema actually looks like once an application has shipped and grown past the tutorial stage. A handful of real issues turned up during the read, and each one is going to the project that owns it, privately, before anything about it is written here. What is left, once those are set aside, is more interesting anyway. These projects share conventions they never discussed, because the framework or the ecosystem around it chose first.

Two different reads sit behind this piece, and they cover different sets, so I keep them apart throughout. The relationship counts cover all fifteen applications. The structural checks are slower, and some of these applications could not run the tooling at the time, so they cover a smaller set: twelve databases and 482 tables, of which seven are real applications and five are bare Laravel baselines kept as a control. Wherever a number appears below, it says which of the two it came from.

A table nobody wrote on purpose

Six tables across four of these projects have no primary key at all. In Bagisto there are three of them, password_resets, admin_password_resets and customer_password_resets. Firefly III and Koel have one each under the first of those names. Twill has one under its own prefix. All six carry the same shape:

email        varchar(255) NOT NULL,
token        varchar(255) NOT NULL,
created_at   timestamp NULL,
KEY (email)  -- and nothing declared PRIMARY

That shape is not a mistake any of these four projects made. It is Laravel's own old scaffold, the one every project generated for years by default. Laravel has since replaced it: a current Laravel 13 install ships a table named password_reset_tokens, with the email column as an actual primary key.

Twill is the clearest evidence of what happened here. At some point it renamed its copy to twill_password_resets, its own name in its own migration, and kept the old keyless design anyway. Nobody sat down and decided a password reset table should have no primary key. A framework generator made that call years ago, and it has been carried forward ever since by projects that had no reason to look at it again.

Read this one carefully: it says something about how Laravel scaffolding propagates, not about carelessness in any of the four projects that still carry it.

How connected is a real schema, actually

The strongest finding in this census did not come from the structural rules at all. It came from a much simpler question, asked of all fifteen applications: of all the tables in a schema, how many actually sit in at least one foreign key relationship with another table?

App	Tables	Foreign keys	Tables in a relationship
Bagisto	146	185	87%
Monica	100	138	86%
Lunar	75	82	85%
Firefly III	81	114	79%
Koel	40	42	75%
Pterodactyl	35	35	74%
InvoiceShelf	49	79	69%
Lychee	52	55	67%
Azuriom	28	22	64%
Twill	24	4	33%
Cachet	32	3	16%
BookStack	41	4	12%
Snipe-IT	58	1	3%
October CMS	41	0	0%

Statamic is the fifteenth and is not in this table, for a reason that gets its own section below.

Look at the bottom of that list. Snipe-IT is a mature asset manager with 58 tables held together by exactly one foreign key. October CMS has 41 tables and none at all: its core modules carry 35 relation declarations in plain PHP, belongsTo, hasMany, morphTo, the usual Eloquent vocabulary, and not one line outside vendor/ ever calls ->foreign(). The relationships are real. The database enforces none of them.

Put another way: half of this corpus would draw an ER diagram (ERD) with almost no lines in it, not because the relationships are missing, but because they live somewhere a diagram cannot see.

That is not a defect anywhere on this list. It is a real fork in how Laravel applications get built, sitting in plain sight, that nobody had put a number on before. One half of this corpus leans on the database to hold its relationships together. The other half keeps every one of them in application code and asks nothing of the schema. Both are working software. They are just built on two different assumptions about what a database is for.

Portability has a cost, and it is the foreign key

Part of that split has a plain explanation. Several of these projects ship migrations designed to run on more than one database engine, MySQL, PostgreSQL and SQLite alike. That choice has a direct, visible cost in the schema, and the foreign key is the main casualty.

Cachet is the clearest example: 32 tables, and 3 foreign keys between them. Its schema is full of columns that are clearly meant to reference another table, with _id naming, the right type, sitting right next to the table they point at, and no constraint declared. A ->foreign() call is tied to a specific engine's constraint syntax in a way a plain integer column is not, so a schema meant to run anywhere gives up the constraint to keep that promise.

This is worth holding on to before reading the bottom of the table as a quality signal. A self-hostable project that has to work on whatever engine somebody happens to have is under a constraint that a private application, built for one engine from day one, never faces.

What a starter kit adds, and what a flat-file CMS does not

Two results here are not surprises, and both are worth stating plainly, because they rule things out.

The first is about starter kits. The structural read included a bare Laravel skeleton as a control, migrated with nothing else installed, and three of the common ways a project gets started on top of it. Breeze and Filament both landed on exactly 9 tables, the same count as the bare control, with nothing flagged at either. Jetstream adds five more tables for team support and still comes back with nothing flagged under the default profile. So the schema a brand new Laravel project starts with does not really depend on which of those gets picked. That is worth knowing before assuming a schema problem in a young project came from a starter kit choice, because it almost certainly did not.

The second is Statamic, and it is why it sits outside the table above. Statamic scored exactly the same as the bare control: 9 tables, nothing flagged. That is the expected result rather than a surprising one, and it is easy to forget while reading a column of percentages. Statamic is a flat-file CMS. Content lives in files, not rows. Its database only exists for the parts of Laravel that need one, sessions, cache, the usual scaffolding. Ranking it on how connected its schema is would say nothing, because it has no application tables to connect.

What this does and does not show

Every codebase here publishes its source, but the licence is not what creates the bias, and it is worth being precise about that. Twelve of these fifteen are MIT, AGPL or GPL. Three are commercial products that happen to ship readable source: Cachet, October CMS and Statamic. What all fifteen actually share is a distribution model. They ship to infrastructure they do not control, so their migrations have to run on whatever engine the person installing them happens to have.

That is the pressure that suppresses foreign keys, and it falls just as hard on the three commercial ones as on the twelve. A private application, built for one engine from day one and deployed only by the team that wrote it, is under none of it and will look far more connected as a result. That is a different population, and this census cannot see it.

One application that was meant to be in this set never finished. Coolify's migrations stop partway on MySQL: one index name resolves to 72 characters, past MySQL's limit of 64. That is not a defect in Coolify. It is a PostgreSQL-first application being exactly that, on an engine it was never designed for, and it could not be rescued by switching engines, because one pinned MySQL is the first rule of this setup.

The instrument, briefly

Every schema here was read with truss:doctor, a structural check I built into Laravel Truss. It is the reason this census could happen at all: it is what turned hundreds of tables across fifteen databases into something one person could actually read in a reasonable amount of time. Structure only, never data.

It is not the subject of this piece, and any real issue it turned up along the way goes to the project that owns it before it goes anywhere public. That is not a promise made only here: the list of applications it has been run against says the same thing, and deliberately publishes no findings.

What is public is the part that is not anybody's fault. A lot of what looks like a schema decision in a mature Laravel application was never really decided by that application at all.

The bug that only showed up once strangers could paste a schema

Alberto Arena — Mon, 24 Aug 2026 12:14:22 +0000

People kept asking the same question about the schema viewer I maintain: "what does this look like on my schema?" The demo only ever offered a sample database to look at, so the honest answer was "install the package and point it at yours." That's a fair amount of friction for someone who just wants to see whether the tool is worth their time.

So I added a page that parses a pasted mysqldump in the browser and draws it with the same dashboard the package ships. No install, no upload, nothing leaves the tab. That part was the easy sell. The part worth writing about is everything the code had been getting away with, because until that page existed, every schema it had ever drawn came from a database connection the person running it had configured themselves.

A connection string is a small trust decision that's easy to forget you made. You typed it, or an environment variable did, and either way something you controlled put it there. A pasted file has no such history. It could be a colleague's export, a tutorial's sample data, or nine hundred lines of MySQL DDL from someone you've never met. Same parser, same renderer, same code path, wildly different set of things it's now allowed to assume.

Assumption one: names are just strings

The dashboard builds a diagram definition by writing table and column names straight into it. That's fine when a name came from information_schema, because a database enforces its own identifier rules before a name can exist. It stops being fine the moment a name can come from anywhere: nothing stops a pasted file from naming a column something that isn't a database identifier at all, it's a fragment of markup for whatever's rendering the diagram.

Read from a live connection, that string had already been validated by something else before it ever reached this code. Read from a paste, the validation had never happened, and the rendering code had no way to know the difference because it never checked. The fix wasn't clever: every identifier gets reduced to what the diagram format actually accepts before it's written anywhere, consistently, on every reference to that name. But it's worth sitting with what made the bug possible in the first place: correct code, wrong assumption. The string-writing was never wrong. What was wrong was believing every string that reached it had already been through a gate it hadn't actually been through.

Assumption two: an unhandled case can stay quiet

A schema dump is not one grammar, it's whatever the tool that produced it decided to write, and that varies more than you'd expect: backtick-quoted identifiers or not, a CREATE INDEX as its own statement or folded into the table definition, foreign keys added later with ALTER TABLE instead of declared inline. A parser that only handles the common shapes will hit a line it doesn't recognize eventually, and the question is what happens next.

The tempting answer is: skip it and move on, the diagram still mostly works. That's the wrong answer for a page whose whole job is showing someone their actual structure. A single dropped constraint doesn't make the diagram look broken. It makes it look complete and wrong, which is worse, because nothing about the output tells the reader to doubt it. So every statement now gets one of three outcomes, and all three are visible: parsed and drawn, deliberately skipped and counted, or flagged with the line number that produced it. A summary line reports the second and third categories up front, not buried in a details panel nobody opens. If ten tables came from a real database and the diagram shows nine, silence is the bug. Saying so is the fix.

Assumption three: an unnamed relationship isn't a real one

Truss has an inference mode elsewhere that guesses relationships from naming conventions, user_id probably points at users even without a declared foreign key. That's a genuinely useful feature when you opted into it and can eyeball the result against a schema you know. It's a bad default for a page whose output is the first and only thing a stranger sees. A guessed edge that's wrong doesn't read as a guess. It reads as the tool telling you something false about your own database, with no indication it was ever uncertain.

So the paste-parser draws only what's explicitly declared, a FOREIGN KEY constraint or nothing. A column named exactly like a foreign key convention, with no constraint behind it, produces no edge at all. That's a narrower feature than the inference mode elsewhere in the same package, on purpose: precision matters more than completeness when the reader has no way to independently check your work.

The bug that hid behind a passing test

One more, because it's not about untrusted input at all and I'd have missed it without a different kind of check. Reviewing the page before it shipped, every click led back to the project's GitHub repo, no matter what part of the page you clicked. The cause was a missing closing </a> tag, several lines up, that had nested the entire rest of the shell inside a single link.

The existing tests for that page matched strings with regular expressions. A regex has no concept of "this tag is still open ten lines later." It saw the opening <a>, saw a plausible chunk of markup after it, and passed, the same way it would have passed if that tag had been closed correctly three lines down instead of never. What caught the bug in the end was a structural check, one that actually parses the HTML and confirms every tag that opens also closes, and the self-test that check needed was the same broken markup fed back into it on purpose.

The lesson generalizes past HTML: a test that pattern-matches text is checking that certain substrings exist, not that the thing you shipped has the shape you think it has. Those aren't the same guarantee, and the gap between them is exactly where a test suite stays green while a page silently breaks.

Structure only stays true, on purpose

None of this changed what the tool promises: structure only, never data. Any INSERT statement in a pasted dump gets counted and discarded, not read, and that count is reported so the promise is something you can watch rather than something you have to take on faith. The parsing itself runs entirely in page code, the result reaches the dashboard through an in-memory blob URL, and the only thing written to sessionStorage is used to survive a page reload and gets deleted the moment it's read. Nothing is uploaded, because there's nowhere on a server for it to go.

That promise was never the hard part. The hard part was noticing how many other things the code had quietly been trusting, once "your own database connection" stopped being the only way data could arrive.

Truss is the Laravel schema viewer I maintain. You can try it on your own schema, no install required, at trussphp.com/demo/your-schema. Structure only, never data.

Context Engineering: The Discipline That Keeps AI From Writing Slop

Alberto Arena — Mon, 17 Aug 2026 10:43:55 +0000

"The art of providing all the context for the task to be plausibly solvable by the LLM."

Tobi Lütke, Shopify CEO, on X, June 19, 2025

That's the definition Tobi Lütke gave the term "context engineering" when he decided he liked it better than "prompt engineering." I think it's the right definition, and I think most people complaining about AI slop are one inference away from noticing why.

A vibecoder who fires a prompt at an agent with no project context isn't getting a worse model than the one I use. They're getting the same model doing its honest best with nothing to ground it: no rules file, no memory of yesterday's decisions, no pointer to the component that already solves this. So it invents something plausible. Inconsistent naming, a reinvented helper that already exists three files over, an architecture assumption that was wrong two refactors ago. That's not the model being bad. That's the model being under-informed, confidently.

Anthropic, LangChain, and the team behind Manus have all converged on the same finding from production agents: most agent failures are context failures, not model failures. Bad context in, sloppy software out.

The four ways context goes wrong

The clearest breakdown of how context fails comes from Drew Breunig's How Long Contexts Fail: poisoning, distraction, confusion, and clash. What follows is my own relabeling of those four, translated into what each one actually looks like in a codebase rather than restated in Breunig's original terms:

Failure mode	What it looks like
Burst	Everything gets dumped into context upfront, so the one relevant fact is buried under forty irrelevant ones and the agent weighs them about equally
Poisoning	One wrong or hallucinated detail early in a session (a method that doesn't exist, a convention that was never real) gets treated as fact for the rest of it
Noise	The context is technically all relevant, just too much of it, so the signal-to-text ratio collapses and the agent can't tell what actually matters right now
Conflict	The system prompt says one thing, the project's rules file says another, and the agent has to guess which one wins, silently, every time

None of these are model problems. They're all things a human decided, or failed to decide, about what the agent sees and when. Which means they're fixable the same way any other engineering problem is fixable: on purpose, not by accident.

What it looks like when it's done on purpose

I'd rather show this than diagram it, so here's the actual CLAUDE.md from Truss, a Laravel package I maintain. It's 52 lines long, it states the stack, the commands, and a short list of invariants that must never break, like "no data exposed, ever, only structure," and then it stops:

## Pointers

- Architecture and domain model: `docs/DESIGN.md`
- Phased build plan: `docs/INSTRUCTIONS.md`
- Decision log: `docs/DECISIONS.md`
- Path-scoped rules (auto-load when matching files are touched): `.claude/rules/`

This file should stay short enough to read in under a minute. If you're
about to add detail, it probably belongs in `docs/` instead, with a
pointer added here.

Everything that isn't needed on every single turn lives one hop away instead of sitting resident in context by default. That's not a documentation choice, it's a context budget: the file names its own constraint and holds itself to it. Those .claude/rules/ files are real, not a placeholder: introspection.md scopes to src/Introspection/**, frontend.md to resources/js, resources/css, and resources/views, release.md to CHANGELOG.md, each one loading only when Claude actually touches a matching path, not resident by default the way CLAUDE.md itself is. I've written up the fuller mechanics of how that split works, RAM versus demand-paged rules versus skills versus disk, in CLAUDE.md Is RAM, Skills Are Not Disk, if you want the reasoning behind the shape rather than just the result.

The point here isn't "copy this file." It's that the file is small enough to audit. Compare that to the ordinary case: a three-hundred-line CLAUDE.md nobody's re-read in months isn't context engineering, it's context archaeology, and the agent is the one doing the digging, badly, every session.

Three checks, not a checklist

A checklist gets skimmed once and forgotten. What actually holds a team to this is something mechanical enough to enforce, so here are three checks, in ascending effort, none of which require trusting anyone's discipline going forward.

A line budget. Truss's CLAUDE.md states its own limit in prose, "short enough to read in under a minute", but doesn't enforce it, and reading time isn't something CI can check directly. Line count is the closest cheap proxy, so here's what that could look like as a CI step (120 is my own suggested threshold, not a number Truss enforces today):

- name: Keep CLAUDE.md readable in under a minute
  run: |
    LINES=$(wc -l < CLAUDE.md)
    if [ "$LINES" -gt 120 ]; then
      echo "CLAUDE.md is $LINES lines, over the 120-line budget. Move detail to docs/."
      exit 1
    fi

Cheap, mechanical, and it's enforcing a rule the file already claims for itself.

A drift check. This is the one I trust most, because it's the same idea Truss already applies to database schemas. A committed export file, checked against the live schema, build fails if they've drifted apart:

php artisan truss:export --output=schema.dbml --check

It compares the freshly generated export against whatever's already committed at that path and exits non-zero if they don't match byte for byte, the same mechanism as git diff --exit-code for a generated file, just schema-aware. Context files rot the exact same way, except what's usually committed is nothing: no file that gets checked against the thing it describes. Does every path CLAUDE.md points to still exist? Was docs/DESIGN.md last touched before the architecture it describes changed? A pre-commit hook or CI step that resolves every referenced path and flags anything missing or stale catches the failure mode that actually bites: an agent working confidently off documentation that quietly stopped being true.

Golden-task regression checks. A small, fixed set of representative prompts, "add a new artisan command," "explain the authorization gate", run periodically against whatever the current context bundle produces, with the expected shape of the answer written down somewhere. This one doesn't fully automate. But even a manual pass before a release catches the case the other two checks can't: a change to a rules file that's individually reasonable but breaks something two files away, silently, because nobody asked the agent to actually do the task before shipping the instruction change.

None of these are exotic. They're linting, drift detection, and regression testing, the same three things you'd already reach for if the artifact in question were code instead of prose. That's the actual point: it is code, in every way that matters except syntax highlighting.

The discipline is the whole difference

The vibecoder fires prompts into a context vacuum and ships whatever comes back, because "prompting" is the only lever they know is there. The engineer treats context, the rules file, the memory, the docs it points to, as a first-class artifact: versioned, reviewed, budgeted, checked for drift, same as anything else that ships. Same model, same tool, wildly different output, and the difference was never the prompt.

If you're looking at a vibe-coded app that feels inconsistent, half-finished, confidently wrong about how your own codebase works, don't ask what model built it. Ask what it was allowed to see.

My coding agent kept inventing columns

Alberto Arena — Mon, 10 Aug 2026 14:30:52 +0000

Ask a coding agent to write a query against a table it hasn't seen this session, and it will guess. Confidently, plausibly, and wrong: a foreign key named author_id when the column is actually created_by, a status treated as a free-text string when it's a tinyint enum, a table it's sure exists because a table like it usually does. It isn't lying, it just doesn't know, and nothing forces it to say so.

The usual fix is pasting a schema dump into the chat at the start of a session. That works until the next migration, at which point it's just a different kind of wrong: confidently out of date instead of confidently invented.

There's an obvious third option: let the agent run queries itself, most coding agents can already execute SQL. But that means handing over real database credentials, and a connection that can query can also see rows, not just structure. That's a bigger grant than the problem needs.

Truss has always been a live, zoomable ER diagram of your Laravel app's real database schema, structure only, never a row of data. Version 1.8 points that same live structure at a coding agent instead of a browser tab.

Give it meaning a type can't carry

A column tells an agent its name and type, not what it means. status = 1 doesn't say "paid" on its own. Annotate it once and every export carries it:

// config/truss.php
'annotations' => [
    'source' => ['config', 'database'],
    'tables' => [
        'orders' => [
            'note' => 'One row per checkout attempt, not per completed order.',
            'columns' => [
                'status' => 'tinyint: 0 pending, 1 paid, 2 refunded',
            ],
        ],
    ],
],

If your database already carries COMMENT strings on tables and columns, leave 'database' in annotations.source and Truss reads those directly, no duplicate config to keep in sync. Either way, a comment is part of the CREATE TABLE definition, not a row: still structure only. Strip them from any single export with --no-annotations when you just want the bare shape.

Trim it to what the question needs

A forty-table schema is a lot of tokens to spend on a question about one table. --compact drops column defaults and non-unique indexes without dropping a single table, column, or foreign key. --focus=orders --depth=1 narrows the export to one table and its foreign-key neighbourhood, the same idea as the dashboard's focus mode, now available from the command line. And there's a new llm format alongside the existing five (DBML, JSON, CSV, Markdown, Mermaid), a dense plaintext export tuned for a token budget rather than for a human reading a data dictionary:

php artisan truss:export --format=llm --focus=orders --depth=1 --compact

That's what the export produces. Calling it is just as direct, in code or over HTTP.

Building the same thing in code goes through a new fluent, immutable Truss facade instead of the command:

Truss::snapshot()->focus('orders', depth: 1)->compact()->toDbml();

And a gated GET {prefix}/export/{format} route serves the identical output to any HTTP client, behind the same viewTruss gate as the dashboard. Command, facade, route, dashboard download: one pipeline underneath all four, so they can never quietly disagree with each other.

Ask it live, instead of pasting a snapshot

The part I actually wanted, though, wasn't a better export. It was not exporting anything at all.

Truss 1.8 adds an optional server for MCP, the Model Context Protocol that Claude Code, Claude Desktop, and Cursor use to reach outside tools. Built on laravel/mcp, it talks to a coding agent directly over local stdio:

composer require laravel/mcp
php artisan mcp:start truss

Point one at it and the agent gets five tools, list_tables, describe_table, get_schema, focus_table, and get_structural_review, plus a truss://schema resource, all reading the live schema on demand. Every tool advertises MCP's readOnlyHint, so a client can present them as read-only instead of prompting for write approval on a call that was never going to write anything. No row data, ever, and the same exclusion and managed-connection safeguards as the rest of Truss apply here too, opt-in and off by default behind truss.mcp.enabled.

I pointed it at a real project I've worked on for a while, in Claude Desktop, and the difference was immediate: instead of me pasting a schema dump at the start of the conversation, or the agent asking me to run a query to check a column name, it just called describe_table before it wrote anything, the same check that would have caught the guessed author_id from the start of this post. No staleness, because there's nothing to go stale, it's reading the same live introspection the diagram uses.

Try it

Live demo, running against a fictional schema
AI context guide: trussphp.com/guides/ai-context
MCP server guide: trussphp.com/guides/mcp-server
Full changelog: CHANGELOG.md on GitHub

Update with composer update albertoarena/laravel-truss, and if you want the MCP server too, composer require laravel/mcp on top.

What's next

More truss:doctor rules and CI-native output formats are next on the roadmap, followed by reading Eloquent relationships for semantic edge labels instead of raw foreign keys, and navigation aids for schemas with a hundred tables or more. If a tool the agent needs isn't there yet, or an annotation source you'd want isn't supported, open a discussion.

Claude Code Auto Mode: What Still Needs a Human

Alberto Arena — Mon, 10 Aug 2026 08:43:01 +0000

Starting August 14, auto mode becomes the default permission mode for Claude Code on Pro, Max, and Team plans. Buried in Anthropic's own announcement is a number worth sitting with: in a controlled test with 1,053 paid professional testers, researchers swapped in genuinely dangerous commands partway through real sessions. Humans caught 13.6% of them. Auto mode's classifier caught 89%.

That's not a subtle gap, and reading it made me a little uncomfortable, because I've spent most of the last few months running my own sessions in accept-edits or auto mode, clicking through permission prompts the same way everyone apparently does. Anthropic's own usage data backs that up: people approve 97% of ordinary permission prompts, and the rate at which someone actually catches a dangerous one degrades from roughly 17% early in a session to about 5% after fifty-plus prior approvals. We're not reading carefully. We're pattern-matching on "this looks like the last forty things I clicked yes on," and that pattern breaks exactly when it stops holding.

	Human review	Auto mode classifier
Dangerous commands caught (1,053-tester study)	13.6%	89%
Production-severity unintended harm, real flagged sessions	6.3%	2.4%

The second row comes from Anthropic's audit of real, already-flagged sessions rather than a lab test: manually-approved sessions contained serious unintended harm more than twice as often as auto mode sessions did. Different methodology, same direction.

What actually changes on August 14

Auto mode itself is a fairly simple change to the default flow. Right now, Claude pauses before most file edits and shell commands and waits for you to click approve. Under auto mode, it doesn't. Instead, a separate classifier model reviews each action in the background as Claude proposes it, and only interrupts you when it judges something risky: an irreversible action, a request that escalates beyond what you asked for, an attempt to send data somewhere it shouldn't go. Everything else, the reads, the routine edits, the ordinary shell commands, runs without a prompt at all.

The classifier sits underneath the permission mode you've already picked, not instead of it. Your allow, ask, and deny rules resolve first; the classifier only gets a say on whatever those rules don't already settle. That layering is exactly what makes the rest of this post possible: the classifier isn't the only thing standing between Claude and a bad command, it's the last one, and everything upstream of it is something you configure.

The asterisk Anthropic puts on its own number

None of this means auto mode is safe, and Anthropic doesn't claim it is. Their own line: "auto mode relies on classification systems and therefore does not eliminate risk." They ran a two-week red-teaming pilot with Apollo Research, injecting synthetic attacks into real workflows. Before the hardening that shipped with this release, the classifier missed 12% of those attacks. After hardening, 7%, on a test set the classifier had never seen during tuning. Better than a distracted human. Not zero.

What the classifier is actually built to catch is specific: scope escalation on a vague or destructive request, credential exploration, exfiltration through an external service like a public gist, retrying a failed deploy with a skip-verification flag, a command that reads normally but was seeded by hostile content Claude picked up along the way. Where it still misses isn't usually "is this dangerous", it correctly flags danger most of the time. It's "does a real consent signal in this session actually cover this specific action", the same ambiguity a tired human glosses over, just less often.

So the useful question isn't auto mode versus manual review. It's what to put alongside auto mode that fails in a different way than auto mode does.

Rules that hold no matter the mode

The classifier isn't the only layer available, and it's not the one you have the most control over. Permission rules sit underneath it: the docs are explicit that "these controls apply in every mode, including bypassPermissions: deny rules and explicit ask rules." Deny is a hard stop the classifier never gets to weigh in on. Ask still forces a prompt, even in a mode whose entire point is skipping prompts, which matters because the example below relies on it.

Here's a concrete gap worth knowing about: auto mode auto-approves pushes to any branch of the repository you're working in, including the default branch, unless you tell it otherwise. The classifier judges the push's content on its own terms, but the act of pushing to main isn't itself something it blocks by default. If you want that to always stop for a human, write it down:

{
  "permissions": {
    "ask": [
      "Bash(git push origin main)",
      "Bash(git push origin master)"
    ]
  }
}

The push example above uses ask on purpose: you still want to push eventually, just with a human in the loop first. That's different from an invariant you never want crossed at all, "no data exposed, ever," say, in a CLAUDE.md file. A rules file states that kind of invariant as a request Claude tries to honor. A deny rule enforces it: a request the tool can't route around, in any mode, on any day you forget you're in auto mode at all.

A gate automation can't talk itself out of

Rules cover what you can name in advance. Hooks cover what you want checked every time, mechanically, regardless of what the classifier decides. A PreToolUse hook can inspect a tool call before it runs and block it outright, deterministically, with no probability involved:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(git push *)",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/require-green-tests.sh"
          }
        ]
      }
    ]
  }
}

#!/bin/bash
# .claude/hooks/require-green-tests.sh
if ! npm test --silent; then
  echo '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"Tests are red, push blocked"}}'
else
  exit 0
fi

The if field narrows this to git push calls specifically, the script runs the test suite, and a failing suite returns a deny decision that blocks the push outright, exit code 2 works the same way with a plain stderr message. Nothing here asks a classifier to judge intent. It's a yes/no gate on a fact you can check.

Review moves, it doesn't disappear

None of the above replaces reading the diff. It changes what "reading the diff" is for. I wrote before about how agentic development turned most of the job into review, and the failure mode there isn't that people stopped reviewing, it's that review quality degrades under volume exactly the way the approval-fatigue numbers above describe. Auto mode doesn't fix that. It just removes the low-value prompts so the review that's left can, in theory, be the kind that actually catches something.

In practice that means picking one point in the loop where you deliberately stay the bottleneck, on purpose, and the push to a shared branch is the obvious candidate. It's the one action that's genuinely hard to undo and visible to someone else the moment it happens. Everything upstream of that, a wrong edit, a bad approach, a half-finished refactor, is still local and still reversible. Hallucinated code compiles and passes a quick glance; it doesn't survive someone actually reading it against what they asked for. That reading has to happen somewhere. Put it at the boundary that matters and let the classifier and the hooks handle the volume everywhere else.

Tests are the check that doesn't get tired

The hook above only works because there's a test suite behind it. That's the other half of the strategy: tests are the executable version of "did this actually do what I asked", and unlike a human on prompt four hundred of a session, they don't get less careful over time. Write them before or alongside the change, not after, and the git push gate above stops being a formality and starts being the thing that actually catches a regression a tired reviewer would have waved through.

Stacking checks that fail differently

None of this makes the miss rate zero, same as auto mode itself doesn't. The point isn't finding the one control that eliminates risk. It's stacking controls that fail in different ways, so the same blind spot doesn't line up twice. The classifier catches the obvious and the fast. Deny rules catch the specific thing you already know matters. Hooks catch what you can specify as a check. Tests catch what you can assert. And a deliberate human read at the point something becomes shared catches the one thing none of the above can judge: whether this was the right thing to build in the first place.

Thirteen point six percent is a bad number for humans working alone. Eighty-nine percent is a good number for a classifier working alone. Neither one is the number that matters. The number that matters is what's left over once you've stacked both, plus the checks that are actually yours to configure.

Sources

Auto mode is now the default in Claude Code for Pro, Max, and Team plans: the announcement this post responds to, including the 1,053-tester study and the real-session audit numbers.
How we built Claude Code auto mode: a safer way to skip permissions: the technical writeup covering the classifier's two-stage design and what it's built to catch.
Choose a permission mode: official documentation on default, acceptEdits, bypassPermissions, and how permission rules interact with each mode.
Hooks reference: official documentation on hook events, matcher syntax, and the PreToolUse block/allow contract used in the example above.

I built a Laravel event-sourcing generator, then the AI version

Alberto Arena — Thu, 06 Aug 2026 06:01:00 +0000

A while back I built a code generator for event sourcing in Laravel: run one artisan command against spatie/laravel-event-sourcing, get aggregates, events, projectors, and reactors scaffolded out. It's deterministic. Same inputs, same output, every time. It just crossed 10,000 downloads on Packagist.

More recently I built a Claude Code skill that produces the same kind of domain code, except it starts with a conversation instead of a command. So the question people keep sending me is obvious: does the AI skill replace the generator?

No. And the reason is more interesting than the question.

The short version, if you skip everything else: AI didn't kill the code generator. It took over the design half of the job and left the deterministic half exactly where determinism still matters.

What the generator is good at

The generator's whole value proposition is determinism. composer require albertoarena/laravel-event-sourcing-generator, then php artisan make:event-sourcing-domain Order, and you get exactly the files you'd expect, byte-identical every run. No tokens, no API key, no network dependency, nothing to review for "did it hallucinate a method." It runs the same in CI as it does on my laptop.

That's exactly right when I already know the shape of the domain: I know the aggregate boundary, I know the events, I just need the boilerplate written consistently. What it can't do is help me figure out whether that boundary is correct in the first place. It assumes I already did the hard part.

What the skill is good at

The skill is not a code generator wearing an AI costume. Its value sits upstream of the code, in a two-gate workflow:

Gate 1, design. It asks focused questions about the domain and produces an Architecture Decision Record: aggregates, commands, events, projectors, reactors, and the invariants holding them together. Nothing gets written until I approve that ADR.
Gate 2, implementation. Once I approve it, it writes tests first, then generates the full domain, and runs the suite. For that cancel-after-ship rule, that means a test asserting the aggregate throws before a line of the aggregate itself exists, not after.

The part that actually matters is Gate 1. "Can cancel still fire after ship?" is a modelling question, and that's the conversation where event sourcing lives or dies. The generator was never going to have that conversation with me. It doesn't ask questions; it executes a decision I've already made.

The real dividing line

Both tools end up emitting similar-looking PHP, which is why people fixate on the overlap. But codegen is the least interesting thing either one does. The line that actually matters is this:

I already know the design → the generator. Deterministic, fast, no review tax, no dependency on an LLM being available or correct.
I'm still figuring out the design → the skill. It's a modelling partner that leaves a paper trail (the ADR) and a safety net (tests written before the implementation exists).

Which one I actually reach for

Honestly, mostly the skill these days. Most of the time I sit down to add a new bounded context, the boundary isn't fully settled yet, and paying for a five-minute design conversation before anything gets written is worth more than skipping straight to boilerplate. The ADR forces me to answer the awkward "wait, should that be an event or a side effect?" questions before they turn into a rewrite.

That doesn't mean the generator's properties stopped mattering. It still gets pulled out whenever the reasons I built it in the first place are the reasons that matter: expanding a domain whose shape is already locked in, running in a pipeline where I don't want an LLM in the loop, or anywhere determinism and zero token cost outrank a design conversation I don't need to have again. I just don't hit that situation as often as I used to, now that the skill exists.

Where I don't use the skill at all

Being upfront about the edges is the point of writing this. The skill is greenfield only. It designs new event-sourced domains; it does not refactor existing CRUD into event sourcing, and it's scoped specifically to spatie/laravel-event-sourcing v7, not Laravel's own event system, not CQRS without event sourcing, not other packages. If that's your situation, neither tool here is the answer, and I'd rather say so than sell you a mismatch.

Try either

If you're modelling a new event-sourced domain and Claude Code is already part of your workflow, the skill installs in two steps: the first points Claude Code at the marketplace (nothing installs yet), the second installs the plugin from it.

/plugin marketplace add albertoarena/claude-laravel-event-sourcing
/plugin install laravel-spatie-event-sourcing@albertoarena

If you already know the shape of the domain and just want the boilerplate, the generator is a Composer install away:

composer require albertoarena/laravel-event-sourcing-generator
php artisan make:event-sourcing-domain Order

Full write-ups of each, if you want the mechanics: the generator, the skill, and the original walkthrough of building a domain with Spatie event sourcing if you're new to any of this.

I gave my schema viewer your app's colours

Alberto Arena — Tue, 04 Aug 2026 11:25:25 +0000

Truss is a live, zoomable ER diagram of your Laravel app's actual database schema, safe to run in production because it only ever reads structure. I introduced it back in July, and it's been part of every client project since, gated behind a viewTruss policy. Two things kept nagging at me. The dashboard was always Truss blue, whatever the client's actual brand was, so it looked bolted onto their app rather than part of it. And the export button, one click for a Markdown data dictionary or a DBML file, only ever got clicked when I remembered to, so the schema file committed to the repo drifted quietly from the real one until someone noticed, usually the hard way.

Truss 1.6 fixes both: a themeable dashboard that matches whatever it's embedded in, and a truss:export command that puts the same output in your terminal and your CI pipeline, no browser required.

Match it to your app

Colours and fonts now live under truss.theme in config, and Truss re-skins itself in both light and dark mode:

// config/truss.php
'theme' => [
    'colors' => [
        'light' => [
            'accent' => '#b45309',
            'accent-secondary' => '#0f766e',
            'background' => '#faf6f0',
            'surface' => '#fffdf8',
            'text' => '#3a2a1c',
            'border' => '#c8873f',
        ],
        'dark' => [
            'accent' => '#fbbf24',
            'background' => '#1b130b',
            'surface' => '#26190d',
            'text' => '#f5e6d0',
            'border' => '#8a6428',
        ],
    ],
],

Only the knobs you set are overridden, everything else stays on the default Blueprint palette, so three or four values are enough to make it look at home. The re-skin runs deep: the diagram's relationship lines, label backdrops, background grid, table rows, and inputs all follow, not just the toolbar chrome. It ships as a same-origin stylesheet, no build step, style-src 'self' still covers it, and a default install adds no extra request at all. Each value is validated before it's written, so a typo falls back to the default instead of breaking the sheet.

Picking hex values by hand isn't required. The new theme builder previews a palette against the real dashboard live, starts from presets (Blueprint, Ember, Contrast) if you'd rather tweak than start blank, and generates the exact config/truss.php snippet to paste in.

Get a schema file without opening a browser

php artisan truss:export --format=dbml --output=docs/schema.dbml
php artisan truss:export --format=json --check

truss:export is the export button's command-line counterpart: the same five formats (DBML, JSON, CSV, Markdown data dictionary, Mermaid), generated straight from PHP, no browser involved. Output is deterministic, the same schema always produces the same bytes, which is what makes --check worth running: point it at the file you've committed, and it exits 1 the moment that file stops matching the database, 2 on a usage error, 0 when everything lines up. Wire it into a commit hook or CI, and schema drift stops being something a reviewer has to notice by eye. Structure only, as always, no network call.

Try it

Theme builder: trussphp.com/theme-builder
Live demo: trussphp.com/demo
Theming guide: trussphp.com/guides/theming
Schema export guide: trussphp.com/guides/schema-export
Release notes: v1.6.0 on GitHub

Update with composer update albertoarena/laravel-truss.

What's next

Lighthouse CI is next on the roadmap: automated performance and accessibility audits across both themes, light and dark. After that: more truss:doctor rules, reading Eloquent relationships for semantic labels instead of just foreign keys, and schema context formatted for AI agents working in the same codebase. If a theme knob is missing or truss:export should support a format it doesn't, open a discussion.

We Became Editors-in-Chief, and Nobody Trained Us

Alberto Arena — Mon, 03 Aug 2026 06:13:59 +0000

Most of my working day now looks like this: I write a prompt describing what I want. An agent produces a diff. I read it, and either approve it or ask for a refinement. Repeat, dozens of times, until the feature is done.

Ask whether that makes us "prompt engineers" and you're asking the wrong question. Prompt wording is a thin skill, learnable in an afternoon. What's actually changed, after twenty-seven years of writing code the old way, is what the job does to your attention. Less typing. Much more reviewing, at a volume and pace nothing in my career prepared me for.

The loop, honestly described

Strip away the branding and agentic development is a review cycle. You describe an outcome. The agent proposes an implementation. You check it against a mental model of what "correct" means for this codebase, this edge case, this architecture, and you either accept it or push back with more context.

That's not a new activity. It's code review, except the author on the other side never gets tired, never pushes back, and produces a plausible-looking diff in seconds whether it's right or not. The volume changes everything. When review is the bottleneck instead of typing, the job's centre of gravity moves with it.

A different kind of tired

The old way was stressful in bursts. You'd hit a bug, lose an afternoon to it, feel the specific frustration of a stack trace that refuses to make sense. Stressful, but the pace was yours. Typing is slow. Debugging forces pauses. Whether you wanted it or not, there was slack built into the rhythm.

Agentic coding removes that slack. The agent doesn't pace itself to your attention span. It just keeps producing diffs, one after another, faster than you'd ever type them yourself. To review well you need prolonged, focused attention, held at a level that used to only show up during the hard parts. There's no natural lull left for your brain to reset in, because generation never slows down to let you catch up. A whole afternoon of that is a different kind of tired than a whole afternoon spent stuck on one stubborn bug, and after twenty-seven years of the old rhythm, this one still catches me off guard some days.

"Prompt engineer" is the wrong name for it

The skill that matters here was never prompt wording. It's knowing what correct looks like before you see the diff: why a query needs an index, why a migration is unsafe under concurrent writes, why a "working" abstraction will hurt in six months. That judgment doesn't come from prompting practice. It comes from having built things, broken things, and paid for the mistakes.

The people getting the most out of agentic tools right now aren't the ones with the cleverest prompts. They're the ones who can look at generated code and immediately spot the one line that's subtly wrong, because they've written that exact bug themselves at some point. Prompting is the interface. Engineering judgment is still the job.

Where this goes in five years

Three things seem likely to me, in no particular order of confidence.

Review becomes the skill we train for, not the one we tolerate. Right now most of us learned to review code as a secondary skill, something you did after learning to write it. If specifying and judging becomes the primary loop, reviewing well, fast and without rubber-stamping, has to become something we deliberately get better at, the way we once deliberately got better at algorithms.

We start designing around reviewer fatigue, not just reviewer speed. Right now most tooling optimises for how fast an agent can produce a diff. The actual constraint is how long a human can sustain high-attention review before quality drops. I'd expect smaller, more frequent checkpoints, better summaries of what changed and why before you dive into the diff itself, and more deliberate pacing, because burning out the reviewer is now the real bottleneck, not the code generation.

The gap between good and bad engineers widens, not narrows. Agentic tools are a multiplier, and multipliers amplify what's already there. An engineer with strong judgment reviews faster and catches more. An engineer without it approves more bugs, faster than before. The floor for "can produce working code" drops. The ceiling for "can be trusted to ship it" doesn't move, or gets more valuable precisely because it's rarer.

The part I'm less sure about

What worries me isn't the loop itself: it's whether the judgment that makes the loop work survives if fewer people spend years building it the hard way. Review is only as good as the model you're reviewing against, and that model used to be built by writing thousands of lines yourself, badly, and fixing them. If the next generation of engineers reviews before it ever really writes, I don't know yet whether that produces the same instincts faster, or a generation of reviewers who can't tell a plausible diff from a correct one.

So no, I don't think we're becoming prompt engineers. I think we're becoming editors-in-chief of our own code, and editing well is its own craft, one most of us are still learning on the job. Where that leaves the next five years is the part I'm genuinely curious about, not the part I have a tidy answer for.

Originally published on albertoarena.it

The schema doctor is in

Alberto Arena — Fri, 31 Jul 2026 05:05:07 +0000

A migration that adds a user_id column with no supporting index passes review every time. It looks fine. Laravel doesn't complain, the migration runs clean, CI is green. Then a few months later someone's staring at a JOIN that touches two hundred rows and takes eight seconds, and nobody remembers why.

That's the class of problem Truss 1.5 is built to catch before it ships: the schema doctor.

I wrote about Truss here in July, a live, zoomable ER diagram of your Laravel app's actual database schema. It's picked up more traction than I expected since then: it's closing in on 300 installs on Packagist and past 70 stars on GitHub, almost entirely word of mouth in the Laravel community. That traction is exactly what pushed the next feature: a diagram is great for seeing your schema, but it doesn't tell you when something in it is wrong. truss:doctor does.

What it catches

Run it and it flags problems that are visible from structure alone:

Tables with no primary key
Foreign keys with no supporting index
Duplicate or redundant indexes
Foreign keys whose type doesn't match the key they reference
Money-looking columns stored as float
Pivots without a unique key, unindexed deleted_at, and more

Thirteen rules in total, across integrity, index, and type categories, each with a stable code (like TRUSS-IDX-001) so you can look it up, silence it, or change its severity.

Rules are engine-aware where it matters: an unindexed foreign key is an error on PostgreSQL and SQLite, but only info on MySQL and MariaDB, since those auto-index foreign keys.

In the terminal and CI

php artisan truss:doctor
php artisan truss:doctor --preset=strict --fail-on=warning
php artisan truss:doctor --format=json

It exits non-zero once a finding hits your fail level, so a migration that introduces a problem fails the build. No AI, no queries, no row data: deterministic and structure-only, safe to run in a commit hook or a CI pipeline against a database you don't fully trust.

In the dashboard

The same findings surface in the dashboard as a new Health panel, the heart icon in the toolbar. Tables with a problem are flagged right on the diagram, the offending column is marked inline, and lower-confidence (heuristic) findings are labelled as such. Same engine, same findings, two front ends depending on whether you're at a terminal or in the browser.

Try it

The live demo has it running against a fictional schema. Open the Health panel and you'll see a handful of foreign keys flagged for a missing index.

Live demo: trussphp.com/demo
Guide, with every rule code: trussphp.com/guides/schema-doctor
Release notes: v1.5.0 on GitHub

Update with composer update albertoarena/laravel-truss, then run php artisan truss:doctor and see what's already in there.

What's next

This is phase one: the engine and the thirteen rules. Suppression files, more rules, and CI formatters are on the roadmap. If a rule feels too noisy, too quiet, or there's a check you'd want that isn't there yet, the discussion thread is open. I'd love to hear what you run it against.

CLAUDE.md Is RAM, Skills Are Not Disk: The Four-Tier Memory Model for Claude Code

Alberto Arena — Mon, 27 Jul 2026 10:30:21 +0000

Claude Code loads CLAUDE.md in full at the start of every session and keeps it resident the whole time, so every line in it is a line you pay for on every turn, whether the task in front of you needs it or not. CLAUDE.md Is RAM, Not Disk split that into two tiers to deal with it: CLAUDE.md holds only what Claude needs every time, stack, commands, invariants; everything else moves to docs/, which loads only when something points Claude there. Working memory stays small and constantly paid for. Long-term memory stays cheap because it's optional.

I wasn't using custom skills when I wrote that post. Once I started, the obvious move was to file them under disk too: they're detail Claude doesn't need every turn, so surely they belong wherever the rest of the on-demand material lives. That reasoning is wrong, and it took checking how skills actually behave in context to see why. A skill is not a document Claude opens when curious. It's closer to a program that gets launched, and treating it like disk is how invariants end up sitting behind a trigger that might not fire.

Here's the model with two more tiers than it had before: CLAUDE.md is RAM, path-scoped rules are demand-paged RAM, skills are installed programs, and docs/ is disk. Each tier answers the same question differently: when does this load, and what happens to it after. Get that question right for a given piece of instruction and the tier picks itself.

Checked against Claude Code v2.1.212 on July 27, 2026. The listing and compaction budgets below are the kind of number that moves; verify them against the current docs before leaning on the exact figures.

What the two-tier model couldn't see

The original test was: does Claude need this every turn, or only sometimes? That question sorts CLAUDE.md from docs/ correctly, but it quietly assumes there are only two ways for something to load: resident from the start, or resident only once Claude decides to open a file. Path-scoped rules and skills both load conditionally, and neither one is "Claude decides to open a file."

A rule loads because a file path matched a glob. That's deterministic, the same way session start is deterministic, just scoped instead of constant. A skill loads because Claude matched a task description to a name in a list. That's probabilistic: it matches text, so it usually fires and sometimes does not. Collapsing those two into "sometimes" and filing both next to docs/ erases the one distinction that actually matters: whether the content is guaranteed to show up when you need it, or merely likely to.

Tier 1: RAM, unchanged

CLAUDE.md still works exactly the way the first post described it: loaded in full at session start, resident every turn after, re-read from disk and re-injected after /compact. Adding three more tiers doesn't change what belongs here, stack, commands, the handful of invariants that must never break. It's still the only tier with no "when does this load" question to answer. The answer is always.

Tier 2: demand-paged RAM, and a correction to the first post

The nested CLAUDE.md trick from the original post still works, but there's a cleaner mechanism for the same job. If you copied that trick into your own project, this is the point where I'd tell you to migrate it. .claude/rules/*.md files with a paths: glob in their frontmatter load into context the same way a nested CLAUDE.md does, when Claude reads a file that matches. The docs say a nested CLAUDE.md is not re-injected after /compact and reloads the next time Claude touches that subdirectory. They don't say the same for rules, and my own testing suggests it behaves the same way.

Leave off paths: and none of this applies. A rule file without it loads at launch with the same priority as .claude/CLAUDE.md itself, so .claude/rules/testing.md with no frontmatter is tier 1 wearing a different folder, not tier 2. The mechanism doesn't decide the tier. The loading behavior does.

What a scoped rule adds over the nested CLAUDE.md it replaces: the glob cuts across the directory tree instead of being pinned to one folder, so "every *.php file under app/Domains, but not the tests next door" is one line, instead of a rule you cannot express. Every rule file also lives in one folder instead of being scattered one per directory, so reviewing what conditional context exists in a project is a single ls, not a find across the tree. Same loading behavior as before, better shape:

---
paths:
  - "app/Domains/**/*.php"
---

# Domain layer rules

Tier 3: installed programs

A skill's name and description sit in a listing Claude can see from the start of the session, and that listing has its own budget: roughly 1% of the context window. When it overflows, Claude Code shortens descriptions starting with the skills you invoke least, so the ones you use constantly keep their full text and a skill you just added competes for space with everything else you've built. None of that costs much, which is the entire pitch: a project can carry thirty skills for a fraction of what thirty paragraphs in CLAUDE.md would cost, as long as most of them don't fire in most sessions.

The moment one does fire, that pitch stops applying. The full SKILL.md body enters context and stays resident for the rest of the session, at the same per-turn cost as anything in CLAUDE.md. Compaction treats it better than you'd expect but worse than the root file: the first 5,000 tokens of each invoked skill survive /compact, shared across a 25,000 token combined budget, filled starting from whichever skill fired most recently. Invoke enough skills in one long session and the ones you called early get dropped entirely, quietly, with no warning that they're gone.

Two things make a skill something other than either RAM or disk. It can bundle scripts that run without their code ever entering context, only the output does, which nothing in CLAUDE.md or docs/ can do. And you can turn off its automatic trigger with disable-model-invocation: true, so it only runs when you type /name, trading the "maybe it fires" problem for "you have to remember to ask." That flag does more than disable auto-firing: it pulls the name and description out of the listing entirely, not just out of the trigger, so a skill set this way is the one case that costs nothing at all until you invoke it. That second point cuts both ways: a skill can also grant itself tool access through allowed-tools, which makes a committed project skill something you review the way you'd review a settings file, not something you skim the way you'd skim a doc. Skills accept a paths: glob too, the same format as rules, but it only narrows when Claude considers firing one automatically, so a scoped skill is filtered, not guaranteed.

Skills are not disk, because disk is passive. A skill is an installed program with an entry in a lookup table, dormant until something calls it, and then it runs. That's also why the failure mode is specific. Putting a procedure behind a skill trigger is fine, because the cost of it not firing once is that Claude does the steps manually instead of running the script. Putting an invariant behind a skill trigger is not fine, because the cost of it not firing once is that the rule silently didn't apply, and a fuzzy description match is a bad place to gamble something that must always hold.

Tier 4: disk, unchanged

docs/ still works exactly the way the first post described it. DESIGN.md, PLAN.md, DECISIONS.md, long prose that humans read too, loaded only when something points to it and only because Claude decided to follow the pointer. It's still the weakest guarantee of the four tiers, and that's correct: disk was always supposed to be the tier you fall back to for material that doesn't need to be certain, only available.

One trap is worth closing here, since it's the most common way people think they're on disk when they aren't. @docs/DESIGN.md inside a CLAUDE.md is not a pointer, it's an import: the file is expanded and loaded into context at launch, same as everything else in the root file. A plain prose reference, docs/DESIGN.md, no @, is what actually stays on disk until Claude follows it. The first post used prose pointers throughout, which was the right call, more by luck than by design.

The four tiers side by side

Tier	Mechanism	Loaded when	Resident cost	Survives `/compact`
1. RAM	Root `CLAUDE.md`	Session start, in full	Every turn	Yes, re-read from disk and re-injected
2. Demand-paged RAM	`.claude/rules/*.md` with `paths:`	Claude reads a file matching the glob	Every turn after that, for the rest of the session	No, lost until Claude reads a matching file again (inferred, not documented)
3. Installed programs	Skill in `.claude/skills/`	Name and description always listed unless `disable-model-invocation`; body loads on trigger	Resident for the rest of the session once triggered	First 5,000 tokens per skill, 25,000 combined, most recent first
4. Disk	`docs/*.md` referenced by path (not `@` imported)	Only if Claude decides to read it	Every turn after Claude reads it	Whatever survives the summary

Read top to bottom and it's also a certainty gradient. Tier 1 is guaranteed. Tier 2 is guaranteed for the files it's scoped to. Tier 3 is probable, or certain only if you invoke it yourself. Tier 4 is optional. Deciding where a piece of instruction belongs is really deciding how much certainty it needs.

Applied to a Laravel and event sourcing project

The starter repo from the first post had three tiers: root CLAUDE.md, docs/, and a nested CLAUDE.md inside app/Domains. It now has all four:

claude-code-laravel-starter/
├── CLAUDE.md                    # tier 1: stack, commands, invariants
├── README.md
├── .claude/
│   ├── rules/
│   │   └── domain.md            # tier 2: paths: ["app/Domains/**/*.php"]
│   └── skills/
│       └── README.md            # tier 3: how to install a project skill
├── docs/
│   ├── DESIGN.md                # tier 4: domain model, aggregates, events
│   ├── PLAN.md                  # tier 4: phased, plan-first implementation
│   └── DECISIONS.md             # tier 4: lightweight ADR log
└── app/
    └── Domains/                  # rules replace the nested CLAUDE.md that used to live here

domain.md keeps the rule that used to live in the nested file: no framework imports in the domain layer, aggregates only record events, events are immutable and past tense. What changed is where it lives: one file in a folder you can review alongside every other conditional rule in the project, instead of a CLAUDE.md you have to remember exists three directories down. .claude/skills/ doesn't ship a fake example skill; it documents how to install the real one, my Laravel event sourcing skill, which designs and generates the aggregate, events, and projector for a new bounded context in conversation.

Four rules to take away

If Claude needs it every turn, it goes in CLAUDE.md. If it only matters inside files that match a pattern, it goes in a rule, not a nested CLAUDE.md. If it's a procedure with steps, a script, or a template, it goes in a skill, and anything that shouldn't fire on its own gets disable-model-invocation: true. If it's long enough that a human should read it too and Claude only needs it sometimes, it goes on disk.

The two-tier version of this held up fine for a while. It just couldn't tell you where to put the thing that runs.

There's no artisan schema:show, so I built one

Alberto Arena — Fri, 24 Jul 2026 06:32:36 +0000

You join a project. Forty tables, half of them undocumented, and a posts table that somehow relates to three other tables you've never heard of. Where do you start?

php artisan db gets you an interactive shell, and from there you're back to whatever dialect your database speaks: .schema on SQLite, DESCRIBE on MySQL, \d on Postgres. Laravel's own db:show and db:table commands are a step up, an overview of your tables or one table's columns, indexes, and foreign keys, printed straight to the terminal. But they're still one table at a time, in text. Nothing shows you the shape of the thing: which tables actually connect, and how, across the whole schema. So you end up either opening a DB client through an SSH tunnel, or drawing the diagram yourself on a whiteboard from memory, which is exactly as reliable as it sounds.

And that's the easy case, when you have shell access at all. On staging or production, where you actually need this the most because that's where the real schema drifted from the migrations, you often don't have a shell. Some organisations block SSH outright for compliance, which is exactly the situation I wrote about replacing with AWS Systems Manager for running Artisan commands. Even with a Run Command session in hand, that gets you a shell again, not a diagram.

So I built Truss.

What it does

Truss is a live database structure viewer for Laravel. It scans your actual schema, not your migration files, and renders it as a scrollable, zoomable ER diagram right inside your app.

Live ER diagram, rendered with Mermaid, of every table and how it connects.
Focus mode: click a table to isolate it and its foreign-key neighbours, centred and highlighted, so you're not staring at forty tables to understand one.
Filter by table name, and toggle native column types against Laravel-style labels.
Map-style pan and zoom, with auto-fit.
Structure only, always. Truss reads tables, columns, keys, and indexes. It never queries a single row, which is the whole point of being able to run it somewhere that matters.
Self-contained: Mermaid and fonts are vendored and served from the package, so it works offline and under a strict CSP. No CDN, nothing phoning home.
Cached and automatic: the snapshot rebuilds after migrations, so the diagram never goes stale.
Export the whole diagram as PNG or SVG, exactly as it's currently filtered and focused, so it drops straight into a design doc or a PR description instead of a screenshot. Per-table exports as JSON or CSV are also available from each table's menu.

Install it, visit /truss, and you get the diagram. No config, no separate service to run.

composer require albertoarena/laravel-truss

By default it's only enabled locally. To use it on staging or production you explicitly enable it and gate access behind a viewTruss authorization gate, so "safe to run in prod" doesn't mean "wide open in prod".

From the command line, too

db:show and db:table get you close, but they're still one table at a time, in text. php artisan truss:show prints that same cached, exclusion-filtered snapshot the diagram uses, as a table: one row per database table, with its column count and foreign-key count, the whole schema at once instead of one piece of it.

php artisan truss:show   # the whole schema as a table, in your terminal
php artisan truss:open   # or jump straight to the diagram

php artisan truss:open opens the dashboard in your default browser, honouring the route prefix and app URL. It prints the URL regardless, so it still works over a forwarded port on a headless host with no browser for it to open.

Both commands live under a truss: namespace rather than schema:. A package squatting Laravel's own schema: namespace is asking for a collision if the framework ever ships a schema:show of its own, which is the joke in this post's title.

Trying it without installing anything

If you want to poke at it before adding it to a project, there's a live demo running against a fictional schema, right in your browser. Pan, zoom, filter, focus a table, no install required.

How it's held up

I've dropped Truss into a few of my own Laravel projects since building it, including ones I hadn't touched in a while, and it's the fastest I've re-oriented myself in a schema I half-remembered. Clicking through foreign keys in focus mode beats reconstructing the relationships from migration file names, every time.

Get started

The documentation covers installation, the quick start, and authorization for non-local environments in more detail. It requires PHP 8.3+ and Laravel 12+.

Feedback welcome, as always.

Known dev.to gotcha from the plan notes: pasting long content into its textarea can silently drop a newline at a random spot and merge two lines (has happened to two code blocks before) — worth a scroll-through of both code fences before publishing.

Claude Code Routines: A Third Way Beyond /goal and /loop

Alberto Arena — Mon, 20 Jul 2026 06:24:20 +0000

A few months ago, Claude Code shipped /goal, a way to stop typing "keep going" every turn and let Claude work until a condition was actually met. That solved a real problem: staying in the loop with an open session so you didn't have to babysit it turn by turn. It didn't solve a different problem, the one where you want Claude to do something and you're not even at your laptop.

That gap just closed. Anthropic added routines: saved configurations that run on Anthropic's own cloud infrastructure, triggered by a schedule, an API call, or a GitHub event, with no open session and no machine required. It's currently in research preview, so behavior and limits may still shift, but the shape of the feature is clear enough to be worth understanding now.

What a routine actually is

A routine bundles three things: a prompt, one or more GitHub repositories, and a set of connectors (Slack, Linear, and other MCP integrations). Package it once, attach a trigger, and it runs on its own from then on, cloning the repository fresh each time and executing as a full, unattended Claude Code session.

There's no permission-mode picker and no approval prompts during a run. Whatever the environment and connectors allow, Claude can do without asking. That's the point (nobody's there to answer the prompt) but it also means the blast radius of a routine is defined entirely by what you scope it to, not by anything you can intervene on mid-run.

Creating one

The fastest way in is /schedule (alias /routines), run inside any CLI session:

/schedule daily PR review at 9am

/schedule in 2 weeks, open a cleanup PR that removes the feature flag

Claude asks follow-up questions about the repository, the prompt, and the cadence, then saves the routine to your claude.ai account. /schedule only sets up schedule triggers though: API and GitHub triggers need the web form at claude.ai/code/routines, where you can also review or edit anything the CLI created. /schedule list, /schedule update, and /schedule run manage existing routines from the terminal.

Three ways to trigger one

Scheduled. A recurring cadence (hourly, nightly, weekly) or a single run at a specific future time. The minimum interval is one hour, so this isn't a replacement for tight polling, it's for the kind of check that genuinely only needs to happen once a day or once a week.

API. Each routine gets its own endpoint and bearer token. POST to it and a new session starts, optionally carrying a text field with run-specific context, an alert body, a failing log line, whatever the caller wants to hand off. That text arrives wrapped in a block that labels it as untrusted data, so a routine's prompt has to explicitly opt in to acting on it. It's a deliberate guard: anyone holding a leaked token can send text, but they can't use it to redirect the routine into doing something the saved prompt never asked for.

GitHub events. Pull request and release events, with filters on author, title, branch, labels, draft state, and merge state. A routine can watch for pull_request.opened on a specific base branch and run your team's own review checklist before a human ever looks at the diff.

A single routine can combine more than one trigger. A PR-review routine might run nightly as a backstop, fire from a deploy script, and also react to every new pull request.

Routines vs /goal vs /loop

The three now cover genuinely different problems, not three flavors of the same one:

/loop re-runs a prompt on an interval, inside a session you have open, on your own machine. No completion check, just repetition. Good for polling a build or babysitting a PR while you're around.
/goal keeps a session working, on your machine, until a separate evaluator model confirms a condition holds. Good for a bounded task you kicked off and want finished properly before you look again.
Routines run on Anthropic's infrastructure, with no session and no machine required, triggered by time, an API call, or a GitHub event. Good for anything that should happen whether or not you're at your desk.

The practical filter: if the automation needs to survive you closing your laptop, it has to be a routine. Neither /loop nor /goal does, both stop the moment the session ends.

Where routines shine

Backlog maintenance. A schedule trigger set to 0 22 * * * (nightly at 10pm) reads issues opened since the last run, applies labels, assigns owners by code area, and posts a summary to a #triage Slack channel before the team's day starts.

Alert triage. A monitoring tool posts to the routine's API endpoint when an error threshold trips. The routine investigates the payload, correlates it with recent commits, and opens a draft PR with a proposed fix, so on-call reviews a diff instead of starting from a blank terminal.

Bespoke code review. A GitHub trigger fires on every pull_request.opened, applies your team's own checklist, and leaves inline comments for the mechanical stuff so human reviewers can focus on design.

Cross-repo porting. A GitHub trigger on merged PRs in one SDK repository ports the same change to a parallel SDK in another language, keeping two libraries in step without someone re-implementing each change by hand.

Where it gets tricky

Everything a routine does carries your identity. Commits and pull requests use your GitHub account. Slack messages and Linear tickets use your linked accounts. There's no separate "bot" identity to fall back on, so a routine with too many connectors attached can do a surprising amount in your name.

No approval gate means the environment is the only safety net. Network access, environment variables, and which connectors are included are configured once, up front, and apply to every run after that. Scope them to exactly what the routine needs, not to whatever happens to already be connected to your account.

Green doesn't mean the task succeeded. A green status means the session started and exited without an infrastructure error, nothing more. Whether Claude actually did what the prompt asked is a separate question you still have to check by reading the run.

Branch pushes are restricted by default. Claude can only push to claude/-prefixed branches unless you explicitly allow unrestricted pushes for a repository. It's a sensible default, but worth knowing before a routine's first PR shows up on an unexpected branch name.

This is a research preview. The API surface ships under a dated beta header, and Anthropic has already said behavior, limits, and field shapes may change. Don't build anything load-bearing on top of it just yet.

Runs share your regular usage quota, plus a separate daily cap. Routine runs draw down the same subscription usage as an interactive session, on top of an account-wide daily limit on how many routine runs can start. Set up several nightly routines and it's easy to assume each gets its own budget. It doesn't, so check your remaining runs at claude.ai/code/routines before you find out the hard way.

Practical advice

Start with a schedule trigger before reaching for API or GitHub triggers. It's the easiest to reason about and the easiest to pause if something looks wrong.

Strip the connector list down to what the routine actually touches. Every connector you leave attached is something Claude can use without asking, on every run, indefinitely.

Treat routine output the same way you'd treat a CI pipeline: review the diff, don't trust the status light. A run that "completed successfully" and a run that "did the right thing" are not the same claim.

If a routine acts on external input (an alert body, a webhook payload), write the prompt to reference that payload explicitly. Otherwise it just sits there as inert context and the routine won't act on it at all, which is the safe failure mode, but worth knowing in advance rather than discovering it during an incident.

Closing thought

/goal solved the problem of staying in a session without re-prompting it. Routines solve the problem of not needing a session at all. Pick the one that matches the problem you actually have, and for the first time, none of them requires bending one tool to do a different job.

Sources

Automate work with routines: official Anthropic documentation for routines, covering creation, triggers, connectors, and limits.
Run prompts on a schedule: official documentation for /loop and session-scoped scheduled tasks, including the comparison against routines and Desktop scheduled tasks.
Keep Claude working toward a goal: official documentation for the /goal command.
Claude Code /goal vs /loop: Stop Typing, Keep Going: the earlier post this one builds on.