I Finally Built a Boilerplate for AI Context Files (Because I Was Tired of Repeating Myself)

Every time I spin up a new project—whether it's a quick Python automation script or a heavier local-first architecture—I hit the same wall. I'd end up writing the exact same AI context files from scratch. A messy brain-dump of architecture notes, a few strict "don't do this" guardrails, and a tech stack list that usually went stale before the weekend was over. I’d tweak them, forget what actually worked, and try to rebuild the whole structure from memory on the next run.

We’re all using AI to write software now; it’s just the baseline for maintaining velocity. But doing the setup manually every time is a massive leak of cognitive energy. I finally decided to stop doing it the slow way and engineered a proper, reusable boilerplate. The kind of setup that scales with the logic of the project, not just whatever is directly in front of me.

Here is the architecture of the fix. Every project now gets exactly two files at the root. They have strictly separated concerns.

ARCHITECTURE.md

This is the conventional one, and honestly, the architecture-as-markdown trend has sticking power because it works. Think of this file as the project's state. It stores the hard facts: the stack, data models, design decisions, environment variables, things we explicitly decided not to build, known bugs, and the changelog.

But here is the twist that makes it actually functional: you are not supposed to manually update this file. This file belongs to the AI. You write exactly one field—a single paragraph describing what you’re building—and the AI handles the rest. On the first run, it reads your description and bootstraps the project metadata. At the end of every session, it updates the file with whatever changed. It stays honest because it is maintained by the exact same entity writing the code. It reads the file when it needs context; you read the file when you want to remember what the hell you decided three weeks ago.

CLAUDE.md / .cursorrules / copilot-instructions.md

If the first file is the state, this second file is the physics engine. The name depends on your editor of choice:

• VS Code + Copilot (My current daily driver) → .github/copilot-instructions.md
• Claude → CLAUDE.md
• Cursor → .cursorrules

The underlying principle is identical. This file is small, and because it rides shotgun with every single prompt you send, every token has to pay rent. It doesn't store project facts. It stores behavior: how to code, what patterns to strictly enforce, what is off-limits, how to handle errors, and exactly when to stop guessing and ask for clarification.

I engineered mine around four pillars that actually matter in AI pair programming: think before coding, prioritize simplicity, make surgical (not sweeping) changes, and execute with a goal-driven focus. It also leans on the "skills pattern" that’s been picking up traction on GitHub (folks like Andrej Karpathy have been pointing this direction, and it is entirely worth the hype).

Three Flavours (Because One Size Fits Nobody)

The main friction point I kept hitting was that a single template is useless. A solo Python CLI tool has a completely different center of gravity than a React app talking to a backend, which has nothing in common with an API serving web, iOS, and Android clients simultaneously. So, I split it into three architectures.

1. Single app One codebase, one output. A CLI, a library, a small web app, a script. Drop in the ARCHITECTURE.md and your editor’s rules file, paste your description, and go.

2. Fullstack (Frontend and Backend together) When frontend and backend live side-by-side, the boundary between them is where things usually catch fire. This template bakes in an API Contract section (the single most critical artifact when two apps talk), plus state ownership, auth flows, and error handling. The rules engine here enforces contract discipline: the AI is strictly instructed not to mutate a data shape without updating both ends of the wire.

3. Multi-platform (Backend + Multiple Clients) When you have an API serving a web frontend, an Android app, and an iOS app, the blast radius of a bad change is massive. This template introduces a Client–API Usage Matrix—a grid showing exactly which client consumes which endpoint, so the impact of any change is visually immediate. It also enforces per-platform storage rules and backwards-compatibility guardrails for mobile apps floating out in the wild that can't be force-updated.

How it Works in Practice

Pick the flavor that matches your architecture. Drop the two files at the root. Feed the AI one paragraph in the ARCHITECTURE.md Project Description field.

That is the entire setup.

On your first prompt, the AI reads your intent, scaffolds the metadata, confirms the stack with you, and starts building. Every session after that, it logs what changed and appends the changelog. When you abandon the project for a month and come back, the AI catches itself up instantly—because it’s been curating its own memory from day one.

Get the Files

You can download the boilerplates below. Fork them, tear them apart, and adapt them to your own stack. If you land on a tighter pattern than what I’ve got, drop me a line. I will absolutely steal it.

• Single app → download
• Fullstack → download
• Multi-platform → download

---