{"slug": "i-stopped-writing-prompts-i-write-the-repo", "title": "I stopped writing prompts. I write the repo.", "summary": "A developer describes shifting from prompt engineering to context engineering, embedding documentation and conventions directly in the repository to improve AI coding assistance. The approach involves writing reasons rather than rules, which generalizes better and keeps documentation accurate.", "body_md": "*Originally published on indiecore.net.*\n\nFor about a year I got better at asking. Longer prompts, worked examples, careful phrasing, a\n\nprivate collection of formulations that seemed to work. It helped for a while and then it\n\nstopped helping, and what bothered me was the inconsistency: the same request would produce\n\ngood work on a Monday and something mediocre on a Thursday.\n\nThe reason is obvious in hindsight and was invisible at the time. On Monday I'd been in the\n\nsame files for an hour and the session knew the codebase. On Thursday I'd opened a fresh one\n\nand asked the same question of something that knew nothing about the project.\n\nThe prompt was never the variable.\n\nThere's a name for the shift now — prompt engineering giving way to *context engineering*,\n\ntuning the whole information environment rather than the request. Written up at industry\n\nscale it sounds like a programme of work. For one person with a small repo it collapses to\n\nsomething much smaller: whatever you'd have to explain to a competent new contributor on\n\ntheir first morning, write it down, in the repo, near the work.\n\nThe pleasant surprise is that this is all documentation you should have written anyway. It\n\njust never paid for itself before, because you were the only reader.\n\n`content/blog/README.md`\n\nis the guide to writing a post on this site. It exists because I\n\nkept re-explaining the same things to myself after a few weeks away.\n\nIt carries a frontmatter table:\n\n| Field | Required | Notes |\n|---|---|---|\n`title` |\nyes | Build fails without it. Aim for under 48 characters — the site name is appended. |\n`date` |\nyes |\n`YYYY-MM-DD` . Controls ordering. |\n`draft` |\nno |\n`true` keeps it out of the site, sitemap and RSS entirely. |\n\nIt has the four post shapes that work here, each with a skeleton. It has the rule about where\n\nimages live. And it has this, which I'll come back to:\n\nPrefer anchors over line numbers.`#head`\n\nand`#<jobname>`\n\nare resolved from the YAML\n\nstructure, so they keep pointing at the right thing when the file changes above them. Line\n\nnumbers silently start showing the wrong code.\n\nAll of that was written for me. It has turned out to be the highest-leverage file in the\n\nproject, because \"write a post about X\" now produces something with correct frontmatter, a\n\nshape that suits the site and the right embed syntax, with no prompt beyond the topic.\n\nThere are only two ways to get that outcome. Paste your conventions into every request\n\nforever and hope you never forget one, or write them once, in the place they belong, and have\n\nthem be true for every session, every contributor, and your own memory in six months.\n\nStandard advice is a single instructions file at the repository root. Mine is deliberately\n\nthin, and the substance sits beside what it governs: writing rules in `content/blog/`\n\n,\n\nbranching and commands in `CONTRIBUTING.md`\n\n, architecture and deploy setup in the root\n\n`README.md`\n\n.\n\nContext-window economy is part of it — a page of relevant rules beats ten pages of mostly\n\nirrelevant ones. But the bigger reason is maintenance. A root file describing five subsystems\n\ndrifts from all five, because updating it is nobody's job in particular. A README sitting in\n\nthe directory it describes gets fixed by whoever was just annoyed by it, which is the only\n\nmechanism I've ever seen keep documentation true.\n\nThis is the one I'd argue hardest for. Compare:\n\n```\nUse #anchors in gist embeds, not line numbers.\n```\n\nwith the version I actually wrote, which explains that anchors resolve from the YAML\n\nstructure and survive edits above them, while line numbers *silently* start showing the wrong\n\ncode.\n\nThe first is a rule. It gets followed while it's in context and dropped the moment a case\n\ncomes up that nobody wrote down. The second is a reason, and reasons generalise. This has\n\nalways been true of good documentation; it's just far more visible now, because you can\n\nwatch an agent extrapolate correctly from a reason and flounder against a bare instruction.\n\nSame inside the code. This comment earns its keep:\n\n```\n// scripts/seo-ping.mjs submits URLs under this key; the crawlers reject the\n// submission unless the matching file is live at the site root.\n```\n\nNothing in the surrounding lines explains why a random hex file has to exist at the site\n\nroot. Delete the comment and the check looks arbitrary, and checks that look arbitrary get\n\nremoved by the next person who reads them (including, eventually, me).\n\nProse rots. Prose that can't rot is better.\n\nPosts here embed code out of a `gist/`\n\ndirectory by filename, and the build fails if the\n\nfilename doesn't exist. That isn't documentation about keeping articles in sync with the code\n\nthey describe; it's a guarantee. A renamed file can't leave a silent hole in a published\n\npost, because nothing gets built.\n\n`npm run check`\n\nis the same trick applied to process — build plus verify, the exact command\n\nCI runs. Not eight things to remember before pushing. One command, and because the pipeline\n\nuses it too, it can't drift away from what CI actually enforces.\n\nAny constraint you can turn into a failing build is a constraint you stop having to explain\n\nto anyone, ever again.\n\nThe most valuable line in my README has nothing to do with architecture:\n\nIt also hosts the privacy policy for every game.\n\nThose URLs are referenced from Google\n\nPlay Console listings — they must not break.\n\nThere's no way to derive that from the code. The routes look like every other route. That\n\nsentence is the only thing standing between a perfectly reasonable refactor and five broken\n\nlinks in live Play Store listings.\n\nAn agent renaming that route isn't being reckless. It's being exactly as careful as the\n\ninformation available to it, which is why the information has to be available. Every\n\ngenuinely irreversible thing in a project deserves one sentence like that, in the file\n\nsomebody would actually have open at the time. (Where I draw that line is\n\n[the blast radius rule](https://www.indiecore.net/blog/blast-radius-rule-ai-coding/).)\n\nThis part changed with agents and I don't think it's said often enough. Out-of-date\n\ndocumentation used to be mildly embarrassing. Now it's actively dangerous, because an agent\n\nwill believe it and act on it, confidently, without the human instinct that says *hang on,\nthis file looks like it's from last year*.\n\nSo context files need the discipline you'd apply to code. If a rule stops holding, delete it\n\nin the same commit that made it false. If a section describes how you wish the project\n\nworked, it doesn't belong. Don't restate what the code already says plainly — a prose summary\n\nof a function is a second source of truth, and the two will disagree within a month.\n\nShort and true beats comprehensive and half-rotten.\n\nMy prompts got shorter. That's the whole visible result.\n\n\"Write a post about the Cloudflare traps\" is a complete instruction in this repo, because the\n\nshape of a post, the frontmatter, the embed syntax, the voice, the publishing flow and the\n\nconstraint about legacy URLs are all written down somewhere the agent will look. In a repo\n\nwithout any of that, the same sentence needs three paragraphs of scaffolding, and I'd forget\n\none, and get something subtly wrong-shaped back.\n\nThe work moved out of the conversation and into the codebase. It feels slower, because\n\nwriting a README is nowhere near as satisfying as watching code appear. But it's the only\n\npart that compounds — a good prompt helps once, and a good repo helps in every session after\n\nit, including the ones you have with other people.\n\nIf you want to know where yours stands: open a completely fresh session, with no history, and\n\nask for something ordinary. Whatever you find yourself explaining before it can start is\n\nexactly what's missing from your repository, not from your prompt.\n\nOriginally published at ** I stopped writing prompts. I write the repo.**.", "url": "https://wpnews.pro/news/i-stopped-writing-prompts-i-write-the-repo", "canonical_source": "https://dev.to/indiecoredev/i-stopped-writing-prompts-i-write-the-repo-o6", "published_at": "2026-09-03 05:11:31+00:00", "updated_at": "2026-09-03 05:52:50.086245+00:00", "lang": "en", "topics": ["developer-tools", "artificial-intelligence"], "entities": [], "alternates": {"html": "https://wpnews.pro/news/i-stopped-writing-prompts-i-write-the-repo", "markdown": "https://wpnews.pro/news/i-stopped-writing-prompts-i-write-the-repo.md", "text": "https://wpnews.pro/news/i-stopped-writing-prompts-i-write-the-repo.txt", "jsonld": "https://wpnews.pro/news/i-stopped-writing-prompts-i-write-the-repo.jsonld"}}