When to add tests and architecture to an AI-built project
Not on day one, not never. The right moment is a signal you can actually watch for, and it is the same signal for both.
~/blog · index
the factory
thinks in public.
Product decisions, broken assumptions, code and proof from a software factory that runs against real repositories. Written from València while the work is still warm.
intentcodeproof
Fresh from the factory
Latest field notes.
Decisions, failures and proof, ordered by publication date.
What is vibe coding? (and where it stops working)
Karpathy named it: you describe what you want and let the model write the code. It is a real technique with a real edge. This is both.
Vibe coding vs AI-assisted engineering: the line that matters
Same tools, same models, same speed. The line between the two is not the code you generate. It is whether you accept it without verifying it.
From vibe coding to production: the bridge nobody explains
You described an app and got one. Now real people use it and you have to keep it alive. This is the crossing from prototype to product, stage by stage.
Vibe coding debt: what you actually owe and when it's due
The interest on vibe-coded software is real, but it is not one number. It is three separate debts with three different due dates.
Start here
The essential routes.
Durable routes through the archive if you are new here.
the master guideBuilding software with AI agents: the operating guideBuilding software with AI agents is now the work around the code: define, specify, execute, verify and learn, held together as one system../read →Spec-driven developmentWhat is spec-driven development?./read →From vibe coding to productFrom vibe coding to production: the bridge nobody explains./read →Operating coding agentsYou do not have a Claude Code problem. You are the runtime../read →Verification and evidenceVerifying AI-generated code: evidence, not vibes./read →Product management in the AI eraProduct management in the AI era: building got cheap, deciding got expensive./read →Product knowledge graphsCode knowledge graphs: what they are and why agents need them./read →The local software factoryThe local software factory: product, code and evidence on your machine./read →AI-first developmentAI-first development framework: context, execution and evidence./read →
Complete library
Explore by problem.
Search every field note or move through the topic map. Every link remains visible to readers and search engines.
Spec-driven development
Reviewing specs before agents build: the cheapest review you will ever do
A spec review workflow catches the expensive mistakes before an agent writes a line. It is the cheapest, highest-leverage review you can...
./read →Spec-driven vs test-driven: rivals or layers?
Spec-driven vs test-driven development is not a rivalry. Tests verify behavior, specs fix intent, and agents need both layers to build safely.
./read →The spec is the contract: what that means in practice
The spec as contract means little without answers: who signs it, who can break it, and how a breach is detected before...
./read →Adding specs to an existing codebase without stopping the world
How to add specs to an existing codebase incrementally, without a rewrite or a freeze, so agents get a contract to work...
./read →Beyond Spec Kit: what spec-driven needs after the spec is written
Spec Kit alternatives miss the point. The real gap is what happens after the spec: keeping it alive and linked to code...
./read →Acceptance criteria agents can actually verify
Acceptance criteria for AI agents must be mechanically verifiable, not ambiguous prose. How to write criteria an agent can check instead of...
./read →Spec vs PRD: what each one is for (and what agents need)
Spec vs PRD: what each document is for, how they differ, and exactly what an AI agent needs from each to build...
./read →Spec-driven without the overhead: a lightweight workflow
Spec-driven development overhead is a real complaint. A lightweight workflow that keeps the contract and cuts the ceremony, with a concrete recipe.
./read →Living specs: specifications that update with the code
Living specs update alongside the code instead of rotting in a folder. How they differ from static specs and what keeps them...
./read →Spec drift: why your spec and your code stop telling the same story
Spec drift is the gap between what your spec says and what your code does. Why AI agents make it worse and...
./read →Software specifications should be portable
Portable software specifications move between agents and tools while retaining their link to code, decisions, and verification.
./read →Spec-driven development: a green build is not a correct feature
I measured how often AI coding agents ship a green build that's actually wrong: 40% raw, 0% with acceptance criteria up front....
./read →From vibe coding to product
Vibe coding vs AI-assisted engineering: the line that matters
Vibe coding vs AI-assisted engineering: the line is not the tools or the speed, but whether you accept generated code on faith...
./read →Scared to touch it: turning fear of your own codebase into a safety net
Afraid to change your own AI-generated code? The fear is a signal. Turn it into a safety net with characterization tests, recovered...
./read →When to add tests and architecture to an AI-built project
When to add tests and architecture to an AI-built project: the signal that tells you a path is load-bearing, and why day...
./read →Your Lovable prototype is now the product: surviving the promotion
Your Lovable or Cursor prototype quietly became the product. How to survive the promotion to production without throwing the code away and...
./read →The security holes vibe coding leaves behind
The security risks of vibe coding: exposed secrets, missing input validation, and unvetted dependencies. Where they come from and how to close...
./read →Vibe coding debt: what you actually owe and when it's due
Vibe coding technical debt in three layers: comprehension, tests, and architecture. What each one costs and when the bill actually arrives.
./read →Every new feature breaks an old one: the missing contract
Why every new feature breaks an old one in AI-built apps: the missing contract between features, and how to install it without...
./read →Foundations under the house of cards: fixing a vibe-coded app without a rewrite
Fix a vibe-coded app without a rewrite: retroactive specs, characterization tests, and boundaries that reinforce a running app in place.
./read →You shipped code you can't read. Now what?
You shipped AI-generated code you can't read. A practical way to regain control of your own app without reading every line or...
./read →The 90-day reckoning: why vibe-coded apps break at month 3
Why vibe-coded apps break around month 3: the reckoning pattern, why it lands on a schedule, and what to do before it...
./read →What is vibe coding? (and where it stops working)
What is vibe coding: a plain definition of the term Karpathy coined, what it's genuinely good at, and the exact point where...
./read →I asked the Codex app to build an app twice. Neither made it to tomorrow.
I asked the Codex app to build the same app twice. Neither survived to the next day. What that says about building...
./read →Operating coding agents
Compaction eats your decisions: managing the context window on long work
Context window management and compaction: why long agent runs forget the decisions that made them correct, and how to budget the window...
./read →Handoffs: passing work between agents without losing the plot
AI agent handoffs between sessions: what has to travel when work passes between agents so the next one continues instead of starting...
./read →Harness engineering: the discipline forming around agent operations
Harness engineering is the emerging discipline of building the loop around a coding agent: context, tools, verification and recovery, not a bigger...
./read →The run died at 2am: recovery as a first-class workflow
Recovering a failed AI agent run: why recovery should be a first-class workflow with checkpoints and resumable state, not 2am heroism.
./read →Your rules file is lying to your agents: keeping instructions alive
Keeping CLAUDE.md and AGENTS.md updated: how to detect stale instructions your agents still obey, and keep your rules files alive.
./read →AGENTS.md, CLAUDE.md, cursor rules: where your decisions should actually live
AGENTS.md vs CLAUDE.md vs cursor rules: what each rules file is good for, and where your product decisions should really live.
./read →Running eight sessions: worktrees, parallelism and the cost of being the scheduler
Parallel Claude Code sessions across worktrees multiply throughput and turn you into the scheduler. Here's the setup and the real cost of...
./read →Agents will drift: engineering for divergence instead of praying against it
AI agents drift from intent by default. Engineer for divergence with reconciliation and gates instead of praying each run stays on track.
./read →Orchestrating multiple coding agents without them poisoning each other
Multi-agent coding orchestration works when agents have isolation, shared contracts, and a reconciliation step, so parallel work doesn't quietly collide.
./read →Memory for coding agents: what should persist outside the chat
Memory for coding agents means deciding what persists outside the chat: decisions, invariants, and state, each in a form an agent can...
./read →Context loss between sessions: the productivity killer nobody budgets for
When an AI agent loses context between sessions, you re-explain decisions that already exist. Here's what gets lost and where it should...
./read →Context engineering for coding agents: when it helps and when it hurts
Context engineering for coding agents: what goes in the window, what persists outside it, and how to stop re-explaining your repo.
./read →Long-running agents need a runtime, not a bigger model
Agents don't need a bigger model. They need a runtime: scheduling, memory, recovery and verification around the work.
./read →No vendor lock-in: route every task to the right engine
From picking one model to governing a fleet of engines. PaellaDoc routes each task to the right agent and profile, deterministic by...
./read →Verification and evidence
A definition of done that survives AI speed
A definition of done for AI development: why the agent's word means nothing, and how to define 'done' as evidence attached instead...
./read →Reviewing code you didn't write: scope first, diff last
Reviewing code you didn't write, at agent scale: why scope comes before the diff, and a review order that survives more code...
./read →The trust gap: why output stopped being the bottleneck
The trust gap in AI-generated code: why output is no longer the bottleneck, and how to build mechanical trust instead of reading...
./read →Verification loops: hooks, gates and the end of self-reported success
Verification loops for coding agents: how hooks, gates and a fail-fix cycle replace an agent's self-reported success with proof it can't fake.
./read →Testing AI-generated code: what changes and what doesn't
Testing AI-generated code: what changes when the intent isn't in anyone's head, what doesn't change about tests, and how to keep tests...
./read →Evidence-based development: closing work with proof attached
Evidence-based development means closing every task with proof attached: what ran, what passed, against which contract, stored where it can be found.
./read →From production to assurance: the new bottleneck in software
Software assurance is the new bottleneck. Agents made producing code cheap; knowing it's correct and coherent did not get cheaper. Optimize the...
./read →Review fatigue: when code arrives faster than you can read it
AI code review fatigue is a throughput mismatch, not a character flaw. Review at the moments that matter: scope, then diff, then...
./read →"Tests pass": anatomy of a false success claim
Why AI agents claim tests pass when nothing ran: the mechanism behind a false success claim, and how to engineer around it...
./read →Done means done: making agents prove completion
Done means done: how to make AI agents prove completion with evidence instead of a confident sentence, and what actually counts as...
./read →Locally correct, globally incoherent: the real problem with AI-generated code
AI writes locally correct, globally incoherent code not because it's dumb, but because nobody manages its context. Coherence is a property of...
./read →Product management in the AI era
An operating model for product teams that build with agents
The roles, artifacts and cadence of a product team that builds with agents. What each one becomes when construction stops being the...
./read →AI-assisted user research without laundering your evidence
Use AI to synthesize real user research, not replace real users. Keep every synthesized claim traceable to a raw utterance instead of...
./read →The PM–engineering bridge: one system from discovery to merged code
PMs and engineers live in separate content worlds. The bridge is one system where discovery, decisions, specs and merged code share identity...
./read →Product decisions with evidence attached
The product equivalent of 'done means done': a decision is not closed until the evidence that justified it is attached and the...
./read →Insight → decision → outcome: the chain AI speed keeps breaking
How to keep the insight → decision → outcome chain traceable when AI speed collapses the middle and leaves you with features...
./read →AI slop with a nice format: the failure mode of AI-assisted product work
AI slop in product management: more PRDs, tickets and decks without better decisions. The failure mode of AI-assisted product work, and how...
./read →Test the riskiest assumption before the agents build the whole thing
Test the riskiest assumption first: cheap building changed the economics of experiments, and why identifying the risky bet still comes before the...
./read →Product discovery with AI: partner for thinking, not for deciding
Product discovery with AI: use it as a partner for thinking, not for deciding, and do discovery without laundering hypotheses into evidence.
./read →Prototype as spec: impossible to misinterpret
Prototype as specification: a working prototype is a spec impossible to misinterpret. What it pins down, and the limits of where it...
./read →You write PRDs nobody reads. The artifact is the problem.
PRDs nobody reads are not a discipline problem. The dead document is the problem. What replaces it is a living decision connected...
./read →Decision logs: ending the "I never agreed to that" problem
A product decision log ends the 'I never agreed to that' problem: what to record, where it lives, and who actually consults...
./read →Making product means installing a behavior, not running a feature factory
Bloomberg costs $32k a year and nobody leaves. Making product means installing a behavior, not shipping features. The only moat left in...
./read →What is a feature factory?
A feature factory is a team that measures success by output shipped instead of behavior changed in users. Signs, causes, the cost,...
./read →Product knowledge graphs
Docs-as-code in the agent era
Docs-as-code with AI: treat the docs pipeline as part of the build so your agents read instructions that are still true.
./read →Knowledge graph vs vector search for code: when each one wins
Knowledge graph vs vector RAG for code: what each retrieval approach is good at, where it breaks, and when to reach for...
./read →Tribal knowledge is a single point of failure
Tribal knowledge in software teams is a single point of failure. What breaks when the one person who knows why leaves, and...
./read →Reading a repo into product artifacts: stories, criteria, decisions
Extract product artifacts from an existing repo: stories, acceptance criteria and decisions. The reverse path, and the one you actually need.
./read →Product memory: what your team forgets and your system shouldn't
Product memory is the decisions, reasons and dead ends your team forgets. Why your system should hold them, and what happens to...
./read →Living documentation: docs that stop rotting
Living documentation stays true because it's derived from the code, not maintained as a separate copy. Why docs rot and how to...
./read →Onboard against the graph, not tribal knowledge
Onboarding against tribal knowledge doesn't scale to people or agents. Onboard against a code knowledge graph the system keeps true instead.
./read →Codebase maps, not bigger prompts
Agents fail on unfamiliar code because they lack a map, not because your prompt is too short. What a codebase map contains...
./read →Product knowledge graph: read your product's shape, not the repo's feature list
A product knowledge graph reads your product's shape instead of the repo's feature list. Why agents and teams need one.
./read →The product brain that maintains itself
A product brain made of notes goes stale the moment your team ships. The fix is a graph that ties code to...
./read →The local software factory
Why native on macOS still matters for developer tools
Why native macOS developer tools still matter: OS integration, Apple Silicon performance and the trust that signing and notarization actually carry.
./read →A factory of one: shipping serious software as a solo founder
Shipping serious software as a solo founder with AI agents. How one person operates like a team, and where the real limit...
./read →Controlling AI costs when every task can burn tokens
Control AI coding costs when every task can burn tokens: budget per task, route by cost, and make token spend visible before...
./read →Bring your own model: API keys, local engines and staying portable
Bring your own model with your own API keys and local engines. Why model portability is an architecture decision, not a settings...
./read →Tools without accounts: what no-signup design says about a product
No-account developer tools reveal a product's incentives. Why skipping signup aligns with the user, what it signals, and the real tradeoffs of...
./read →Your code never leaves: privacy as an architecture decision
Keeping your code and product data local makes privacy an architecture property, not a policy promise. What leaves, what stays, and why...
./read →Cloud vs local AI dev tools: what you trade in each direction
Cloud vs local AI dev tools is a trade, not a verdict. What the cloud does better, what local does better, and...
./read →Local-first AI development: why the factory should live on your Mac
Local-first AI development keeps the harness, state and evidence on your Mac while calling remote models — better latency, cost, privacy and...
./read →AI-first development
Architecture patterns for AI systems
Architecture patterns for AI systems and the constraints that determine when each pattern is useful.
./read →Securing AI code with Snyk: A practical guide
A practical guide to securing AI-generated code with Snyk: scanning, dependencies and catching what the model didn't consider.
./read →When faster AI coding does not improve delivery
AI coding feels faster than it is. Where the productivity illusion comes from and how to get gains that survive the demo.
./read →Why AI-generated code becomes hard to maintain
Why AI-generated code becomes difficult to maintain, and which review, security and context practices reduce that risk.
./read →Principles for maintainable AI-assisted development
The principles behind AI-first development, and why speed without structure turns AI projects into unmaintainable code.
./read →PaellaDoc and context in AI-assisted development
How PaellaDoc frames AI-first development: structure, context and documentation so AI-built software survives contact with reality.
./read →No field notes match that search.
— end of log · 94 entries · more cooking —