Why AI Coding Agents Build Better on a Working Boilerplate

What goes wrong from a blank folder

Ask a coding agent for "a SaaS with logins and subscriptions" in an empty directory and it has to make dozens of decisions at once: framework, folder layout, session handling, database schema, payment flow, email delivery, error handling. Each choice is plausible on its own. Together they often produce an app where two features handle the same thing two different ways, security-sensitive code is written from memory, and nothing has been tested beyond the demo.

The problems compound. Every later prompt has to rediscover how the earlier code works, which uses context and invites more inconsistency. Review becomes hard because every diff is large and touches foundations. This is the path that leads to the production gaps covered in taking a vibe-coded app to production.

What a working base gives the agent

• Fixed decisions. The stack, folder layout and data access style are already chosen, so the prompt is about your feature only.
• Patterns to copy. "Add a projects resource like the existing notes resource" is a far easier instruction than "design a CRUD API". The agent mirrors validation, ownership checks and response shapes that already work.
• Hard parts done once. Webhook verification, idempotency, session handling and rate limits are where plausible-looking code is most often wrong. If they exist and are tested, the agent can call them instead of reinventing them.
• Checks to run. A smoke test and a configuration checker give the agent and you a fast, objective answer to "did that break anything?"

Instruction files: AGENTS.md and CLAUDE.md

Agents read project instruction files before they work. AGENTS.md is an open format supported by many tools, including Codex, Cursor, Gemini CLI and GitHub Copilot's coding agent. Claude Code loads CLAUDE.md at the start of every session and can also use an existing AGENTS.md. A useful file is short and concrete:

# Agent guide
Stack: PHP 8.3, SQLite, server-rendered HTML. No framework, no build step.
Where things live: app logic in app/bootstrap.php, pages in app/views/,
JSON endpoints in public/api.php, webhooks in public/webhooks.php.
Rules: schema changes need a numbered migration plus app/schema.sql.
Every query that reads user data filters by user_id.
After any change run: php scripts/smoke_test.php and php scripts/doctor.php

Instruction files guide the model; they do not enforce anything. Tests and code review are still what catch mistakes. Keep the file current: when the code changes, update the guide in the same commit, or the agent will follow directions to files that no longer exist.

Keep each prompt small and verifiable

1. One feature per prompt, described by its behaviour: who can do what, and what should happen when it fails.
2. Ask for the migration, the code and a test or manual check in the same change.
3. Have the agent run the existing checks and show you the output.
4. Read the diff. Small diffs on a familiar base are quick to review.
5. Click through it in a browser, including with a second account.

This loop is also the most reliable way to keep agent sessions economical, because the agent reads a few known files instead of exploring a sprawling codebase. More on that in building a SaaS with Claude Code.

A worked example

Suppose your product needs "projects" that each user can create and list, and creating one should cost a credit. On a base that already has a user-scoped resource and a credit helper, the prompt can be this specific:

Add a "projects" resource modelled on the existing notes resource.
- Migration: projects (id, user_id, name, created_at), index on user_id;
  also update the fresh schema file.
- List and create endpoints. Every query filters by the signed-in user.
- Creating a project costs 1 credit using the existing credit helper,
  in the same transaction as the insert. Return 402 when out of credits.
- Add a simple list page in the member area using existing UI partials.
Run the smoke test and the config checker and show me the output.

Everything the agent needs to copy already exists, so the diff is a migration, a few functions, two endpoints and one page. You can review it in minutes, and the ownership check and credit debit follow a pattern you already trust. The same request in an empty folder would also have to invent sessions, a credit system and a page layout, and you would have to review all of it.

Pick a base the agent can read

Readability matters more than fashion. A codebase with few layers, direct SQL and long but plain files lets an agent trace a request from route to database in a handful of reads. Deep abstraction and generated code make that harder.

To be fair to the alternatives: Laravel, Rails and Next.js are extremely well represented in models' training data and have strong conventions, which also helps agents. If you or your team already work in one of them, a good starter in that framework is likely the better choice. The point is to start from something that works and is tested, whatever the stack.

Where a boilerplate does not help

A starter covers the plumbing every product needs. It does not decide what your product does, how it should feel or who will pay for it. The novel core of your app is still new code, so it deserves the same care: clear prompts, tests and review. And a boilerplate you cannot read is no better than one an agent wrote for you yesterday.

Check a few things before you commit to one: does it run locally in minutes, does it include tests you can run, are the instruction files current, and does its licence allow the projects you have in mind? A starter that only works with the author's setup, or whose docs describe features the code no longer has, will mislead an agent as readily as it misleads you.

Sources: AGENTS.md · Claude Code: how Claude remembers your project