How to write an AGENTS.md your agents actually follow
How to write AGENTS.md: where to put it in a monorepo, what shape it takes, how long it can get, and why unfalsifiable lines get ignored.
PAELLADOC — The Local Software Factory
Build and run software from an idea or an existing repo. Discovery, specs, sprints, AI agents, code knowledge graphs and evidence—local on your Mac.
Latest posts
Agent skills vs MCP servers vs rules files: what each one costs
Agent skills vs MCP servers vs rules files: when each one loads, what it costs per turn, and how each fails.
When to add tests and architecture to an AI-built project
Adding tests and architecture to an AI-built project on day one wastes effort; adding them never guarantees collapse. The right moment is a signal you can watch for, and it is the same signal for both.
What is vibe coding? (and where it stops working)
Vibe coding is the term Karpathy coined for describing what you want and letting the model write the code. It is genuinely good at some things and genuinely bad at others. Here is the definition, and the line where it stops working.
Vibe coding vs AI-assisted engineering: the line that matters
Vibe coding and AI-assisted engineering use the same tools and the same models. The line between them is not speed or output. It is whether you accept the generated code on faith or make it prove itself.
From vibe coding to production: the bridge nobody explains
Vibe coding gets you a working prototype in an afternoon. Nobody explains the crossing after that: the day the prototype became the product and you still have to keep it running. Here is the bridge, stage by stage.
Vibe coding debt: what you actually owe and when it's due
Vibe-coded software carries debt, but not the single number the metaphor suggests. It is three debts, comprehension, tests, and architecture, each with its own due date.
The security holes vibe coding leaves behind
Code an agent wrote and nobody reviewed leaks in predictable places: secrets in the repo, unvalidated input, and dependencies nobody vetted. Here is the mechanism, and how to close each hole.
The 90-day reckoning: why vibe-coded apps break at month 3
Vibe-coded apps tend to break on a schedule. Weeks of magic, then around month 3 the same app becomes impossible to change safely. Here is why the reckoning lands when it does, and how to meet it early.
Verifying AI-generated code: evidence, not vibes
The generation of code is solved. What isn't solved is trust. An agent that reports 'done, tests pass' has produced the most probable sentence, not a verified result. Verifying AI-generated code means replacing the feeling of completion with evidence you can inspect: the claim, the proof, and the gate between them.