# Will Claude Code Respect Your Boilerplate? 6 Tests

> What makes a repo Claude-proof: instruction files, data-first schemas, thin routes, verification gates. The checklist + starter.

Source: https://boringpush.com/blog/claude-code-saas-boilerplate

## Brilliant agent, feral repo

[Three months of daily Claude Code](https://www.reddit.com/r/ClaudeAI/comments/1u9cbw7/after_3_months_of_using_claude_code_daily_i_think) ended with an uncomfortable pattern: UI correct, agent says done, code compiles — and `POST /api/order` returns 500 on a coupon feature. "AI coding agents are interns with perfect syntax and zero accountability. They can write, but they cannot verify reality." The [13-agent workflow that broke](https://github.com/anthropics/claude-code/issues/46588) sharpens it: ignored instructions, autonomous tool runs past guardrails, shallow reasoning, fabricated file reads — on a $200/mo Max plan running hooks and phase gates. Same root cause in both: the agent was fine, the repo gave it nothing to hold onto.

## The scorecard: rate any boilerplate in 60 seconds

| Claude-proof trait | What to look for | Why it matters |
|---|---|---|
| Instruction files | `AGENTS.md` / `CLAUDE.md` with rules, not vibes | Unconstrained agents invent architecture per session |
| Data-first schemas | Same entity on every database, same verbs | Agents add fields in one place instead of three |
| Thin routes (≤40 lines) | Validate → auth → one call → JSON | No room for dumped logic or skipped paywalls |
| Verification gate | `node --check` + zero-warning lint + smoke test | "Done" means proven, not claimed |
| Additive migrations | No `DROP`, ever | One bad prompt can't wipe prod tables |
| Minimal dependencies | Under ~10 packages | Less namespace to hallucinate in |

Score your current starter out of six. Most score two.

BoringPush was built to score six: a written agent rules file plus reusable skills (including a mobile-session guard), tri-database parity across SQLite/MongoDB/Supabase behind identical behavior, thin API routes with the access check first, and the gate every turn ends at. Ship from anywhere on this Next.js stack and a phone session gets the same fences as a desktop one — the rules live in files Claude reads, not in habits humans forget.

## The Monday test: audition any repo in an afternoon

1. **Read test.** Ask the agent "where do orders get created?" It should cite the real route and data files with line numbers, not narrate from memory. Vague answers = no locality to exploit.
2. **Field test.** "Add `twitterHandle` to users." Watch: one place or five? Same-shape providers turn it into schema + migration + done. Scattered models turn it into an afternoon.
3. **Slop test.** "Add rate limiting." If the diff touches fifteen files and installs a package, the repo failed. If it touches one guard file and zero packages, it passed.
4. **Refund test.** `git stash` the session. Clean tree in one command? Good — small blast radius. Hour-long untangle? The repo has no seams.

## FAQ

### Claude Code vs Cursor vs Copilot — does the repo choice change?

No. The scorecard is tool-agnostic: instruction files, thin routes, and gates help every agent.

Pick the editor you like; fix the repo either way.

### What goes in AGENTS.md vs regular docs?

Rules the agent must obey (never install, additive migrations only, thin routes) go in `AGENTS.md`. Explanations go in docs.

Agents follow constraints; they skim prose.

### My repo scores 2/6. Rewrite or retrofit?

Retrofit in this order: lint gate first (one afternoon, catches everything), thin the hottest three routes, then add the instruction file. Migrations and parity come last — they're structural.

### Do hooks and subagents replace repo conventions?

No — the broken 13-agent workflow ran 89 hooks and still fabricated output. Hooks enforce process; conventions remove the need for heroics.

You want both, but conventions first.

### Why three databases instead of one good one?

Because "which database" is the most rewritten decision in SaaS. Parity makes it a one-variable deployment detail, so neither you nor the agent ever rewrites queries to switch.