AI Is Too Good at Coding - So I Built Something to Keep the Why (and Make It Scale)

Over the past few months I've been building with Cursor, Claude Code, and Codex - same tools a lot of builders are running right now. The pace is genuinely wild. I've shipped MVPs for friends where we went from a rough PRD to a working demo in a single day: auth wired up, database in place, deployed, link sent before midnight. Some of it fully vibe-coded. Some of it structured. All of it fast. You're seeing this everywhere now. Builders spinning up entire products over a weekend, sometimes over an afternoon, because the tools finally keep up with the idea in your head. And here's the thing people undersell: AI coding agents are actually pretty good at following engineering principles - *when they have something to follow*. Hand them a PRD, point them at your conventions, set a few non-negotiable rules, and they mostly stick to it. They'll reuse your components instead of inventing new ones. They'll write tests if tests are part of the standard. They won't skip the boring obvious stuff if the boring obvious stuff is written down somewhere they load every session. The gap I kept hitting wasn't the coding. It was what happened to the decisions along the way. When you move this fast, you make dozens of small calls in chat: which auth flow, which database, what "done" means for this feature, whether this module owns that boundary. The code commits to the repo. The reasoning usually doesn't. It stays in a thread that gets compacted, or a session that ends, or your head - which is a rough place to store architecture when you're juggling three builds at once. I didn't want to slow down. I wanted the speed *and* a durable layer the agent could reload every session: accepted decisions, conventions, quality gates, evidence that work is actually finished. So I built [Persist OS](https://github.com/Karthick-Ramachandran/persist-os) - a local CLI that writes that layer into plain repo files and enforces it with a deterministic `persist doctor` gate. No network. No telemetry. No AI calls. ```bash npx persist-os@latest init ``` ## The actual failure mode Most agent setups treat chat history like it's source of truth. It isn't - it's the thing that evaporates first. Persist OS flips the priority order. Repository memory wins over MCP context, external notes, and chat history. Accepted ADRs and engineering standards outrank whatever the model guessed in the last message. If they conflict, the agent is instructed to stop and report - not quietly pick a side. That's the problem it solves: not "help me remember," but **make the repo authoritative so the next session doesn't start from zero.** ## What `persist init` puts in your repo One command scaffolds the whole memory structure under `docs/` plus `.persist/config.json`: ```txt docs/ 00-product/ PRD, vision, roadmap 10-architecture/ stack, boundaries, decisions 20-security/ threat model, security rules 30-modules/ ownership per module 40-features/ PRD + acceptance + test plan per feature 50-quality/ quality gates 60-engineering/ standards, agent rules adrs/ proposed → accepted decision records ``` It also generates the files your agent actually loads: - `AGENTS.md` - routing rules + Persist commands the agent runs itself - `CLAUDE.md` - short pointer for Claude Code ("read `AGENTS.md`, don't trust chat") - `.cursor/rules/persist-memory.mdc` - always-apply rule in Cursor - `.persist/hooks/pre-commit` - runs `persist doctor` before commits land Pick a stack preset if you want proposed ADRs for real forks (`nextjs`, `python-fastapi`, `laravel-react`, etc.). Every preset decision stays **Proposed** until you explicitly accept it - the schema won't let a preset silently become truth. ```bash persist init --preset nextjs --ai-tools cursor,claude git config core.hooksPath .persist/hooks # enable the doctor hook once per clone ``` ## How I run a one-day MVP with it Say I'm building a checkout flow for a friend's shop. Fast build, but I still want the decisions to stick. **1. Scaffold memory before the agent touches code** ```bash persist feature create checkout ``` That creates `docs/40-features/F-###-checkout/` with `PRD.md`, `ACCEPTANCE.md`, `TEST_PLAN.md`, `TASKS.md`, and the rest - not empty philosophy docs, but the exact checklist the project's delivery workflow expects. The agent isn't supposed to jump straight into `src/`. Module work follows the same pattern: feature docs first, module memory under `docs/30-modules/`, tasks after acceptance criteria and test plan exist. **2. Record decisions as proposals, accept what I mean** ```bash persist adr create payment-provider # writes docs/adrs/proposed/ADR-PROPOSED-payment-provider.md persist adr accept payment-provider # promotes to docs/adrs/ADR-####-payment-provider.md ``` Nothing becomes accepted memory by accident. `persist adopt` on an existing repo and `persist mcp add figma` work the same way - inspect, propose, human accepts. The agent can capture MCP context offline into `docs/ai/mcp/<server>.md`, but Persist never calls the MCP server itself. **3. Let the agent load rules every session** Generated `AGENTS.md` tells the agent what to read and what to run: ```markdown Repository rules override model preferences. If instructions conflict, stop and report the conflict. - `persist doctor` - validate repository memory; run before claiming any work is complete. - `persist feature create <name>` - scaffold feature memory before non-trivial work. - `persist adr supersede <old> <new-title>` - record a changed decision (never overwrite an accepted ADR). ``` In Claude Code, a SessionStart hook injects a live map of accepted ADRs and modules on top of that. Cursor gets the always-apply rule. Codex reads `AGENTS.md` directly. Different mechanisms, same floor: the agent reads the map, follows pointers into detail, doesn't need you to re-paste the architecture every time. **4. Gate "done" with evidence, not vibes** Before the agent can honestly say a feature is finished, the completion loop is: ```bash pnpm test:run && pnpm typecheck && persist doctor ``` `persist doctor` is deterministic - no model judging your architecture. Exit codes: `0` healthy, `1` warnings, `2` errors. Same repo state, same result every time. Concrete things it catches that chat never would: | Check | What breaks | |-------|-------------| | Completion evidence | Feature marked complete but `REVIEW.md` still pending or no test results recorded | | ADR drift | Module doc cites `ADR-0003-auth` but that ADR was never accepted - error | | Superseded decisions | Memory still points at an ADR you've since superseded - warning | | Staleness | `src/` changed six commits ago, memory hasn't been touched since - warning | | Context budget | `AGENTS.md` + Cursor rule + `CLAUDE.md` bloated into a wall of text - warning | So when you're moving fast, "done" means `persist doctor` exits 0 - not "the agent said it looks good." You can add `persist guard --source src` to fail commits where source changed without test files staged. ## What changes when a decision changes Fast builds change their mind. The failure mode there is silent contradiction - code on MySQL, ADR still says PostgreSQL, everything "passes." Persist handles that with `persist adr supersede <old> <new-title>`: old ADR marked superseded, new one links back, Doctor flags anything still citing the old decision. The generated agent rules include the supersede command inline so the model uses it instead of editing history. What it *doesn't* do: automatically detect that your accepted ADR and your current code quietly disagree. That needs reading, not grep. There's a generated `architecture-drift-review` skill for that. The gate stays dumb; the agent does the interpretation. ## Not a vector memory engine (and that's intentional) Tools like supermemory or mem0 solve retrieval - "find me what we said about Auth0." Useful, different problem. I kept losing **accepted decisions with review trails**: where it was decided, whether a human accepted it, whether it's still the decision. That's a files-and-PR-review problem. Plain markdown ADRs, explicit accept/supersede, git diffs. Vector stores can index these files later; they don't replace them. ## When it's worth the overhead **Use it** when someone will inherit the repo - teammate, future you, fresh agent next week. That's when losing the why costs real time. **Skip it** for a throwaway spike you'll delete Friday. No second session, no payoff. The name is the test: persist what should *persist*. Prototype turns into product → run `persist init`. Stay proportional - small fix, just ship it; real feature or architectural fork, write it down. ## Try it MIT licensed. Runs entirely on your machine. ```bash npx persist-os@latest init ``` - **Repo:** [github.com/Karthick-Ramachandran/persist-os](https://github.com/Karthick-Ramachandran/persist-os) - **Why I built it:** [PHILOSOPHY.md](https://github.com/Karthick-Ramachandran/persist-os/blob/main/PHILOSOPHY.md) - **Example outputs per preset:** `examples/generated-nextjs/`, `examples/generated-python-fastapi/`, etc. in the repo If you're shipping MVPs in a day and want the agent to keep following the same rules on day seven - this is what I wished existed. Tell me what breaks when you run it.