Prompt notes inside the repo: what to keep and what to skip

The problem with scattered instructions

Teams usually do write their rules down. The problem is where they put them.

One rule ends up in a chat thread. Another sits in an old ticket. A third lives in somebody's memory after a rushed code review. When work moves fast, that scattered guidance turns into rework.

You feel it quickly with AI coding tools. A developer opens a task, asks for help, and gets a neat answer that ignores the team's real habits. Then someone has to paste the same reminders again: use this folder pattern, avoid that package, keep tests short, name files this way. After a few tasks, the team is teaching the same lesson on repeat.

It gets worse when the instructions live in places nobody checks during normal work. Closed chat threads, last month's tickets, pull request comments, personal notes, and old onboarding docs might each hold part of the story. None gives the full picture when someone is trying to ship a change.

Stale notes create a different problem. A team renames a service, moves a directory, or drops a library, but the old instruction stays behind. Then a person, or an AI assistant, follows yesterday's rule and writes code that no longer fits. Someone else has to catch it, explain it, and review it again. Ten minutes here and twenty minutes there adds up fast.

This hurts most during fast product work. Startups change structure all the time. A note that made sense three sprints ago might now point to dead files, old commands, or patterns the team already stopped using. Bad guidance is worse than no guidance because it looks official.

Short repo notes solve the repeat problem without turning the repository into a diary. They keep the rules that stay true across many tasks right next to the code. That means fewer repeated prompts, fewer avoidable review comments, and less guessing when the next task starts.

What belongs in repo notes

Good repo notes hold the rules people repeat, forget, or learn the hard way. If the same issue comes up in review every week, write it down near the code. If it will probably still matter in three months, it belongs.

The best notes are small and specific. Naming rules are a good example. A short note about how to name services, folders, database fields, or feature flags can cut a lot of noisy review comments. Testing rules work the same way. If every change needs unit tests, a certain command, or a smoke check before merge, say it once in plain language.

Most teams get good mileage from a few kinds of instructions: expected folder and file patterns, test and lint steps to run before review, review rules such as when to include screenshots or migration notes, and project quirks like generated files, fragile modules, or areas with strict backward compatibility.

Project-specific patterns matter more than generic advice. Anyone can guess "write tests" or "keep functions small." They cannot guess that one service reads config in an unusual way, that a shared package breaks if imports move, or that logs must keep certain fields because monitoring depends on them. Those are the details that prevent avoidable mistakes.

This matters even more when a team relies on AI coding instructions. If the repo uses GitLab CI, depends on Sentry dashboards, or relies on generated code and automation, the notes should spell out what must stay intact. One line like "do not rename these fields because dashboards depend on them" can save a messy rollback.

The rule is simple: add notes that help the next person make the right change faster. Skip anything that reads like meeting history, task history, or general coding advice. Good repo notes feel less like documentation and more like a quiet teammate who knows where people usually trip.

What to keep out of the repo

Repo notes work when they explain decisions that will still matter next month. If a note helps one person finish one ticket today, it probably does not belong in the repo.

The first thing to leave out is one-off task advice. "Use this temp script for Friday's import" or "skip test X until Sam is back" might be fine in a chat thread or ticket. A month later, those lines confuse new people and look like permanent rules even though they were short-term patches.

Meeting summaries usually belong somewhere else too. A repo is a bad place for long debates or rough notes from a call. Most of that text ages quickly. What belongs in the repo is the final decision: what changed, why it changed, and where it applies.

The same goes for chat logs. Copying long AI conversations or Slack threads into project folders feels safe, but it creates noise. Nobody should read 200 lines of back-and-forth to find one instruction about naming, testing, or deployment.

A quick filter helps. Leave out personal reminders like "ask Anna for the old password" or "remember my local alias." Leave out temporary workarounds with no end date or owner. Leave out old arguments once the team has made the call. Leave out raw transcripts when one short note says the same thing.

Personal shorthand causes a lot of trouble too. Notes like "use the usual fix" or "same as last time" only work for the person who wrote them. Everyone else has to guess. Repo notes should help a new teammate understand the project without private context.

A better rule is this: keep the final instruction, not the trail that led there. If the team decided to always mock a payment provider in local tests, write that in one clean sentence. Leave the ticket, meeting notes, and side chat in the tools where they started.

Where to place notes so people find them

Placement matters more than polish. A clear note in the right folder gets used. A perfect note buried in a docs pile gets missed.

Put notes next to the code they affect. If a rule only matters for the billing service, keep it with the billing code. If it only matters for one test suite, keep it near those tests. Most people open the folder they need and start there.

Shared rules need one obvious home. Put them in a single file at the top level of the repo so people see them before they edit code. That file should cover repo-wide rules only, such as how AI coding instructions work, what commands to run before a commit, and what not to change without review.

Plain file names help more than clever ones. README.md, NOTES.md, or AI-INSTRUCTIONS.md are easy to spot and easy to remember. Names like ideas-final-v2.md or temporary guidance.md disappear quickly, even in a small repo.

Most teams do fine with a small structure:

• one shared note at the repo root for rules that apply everywhere
• one local note in a folder when that folder has special build, test, or prompt rules
• short code comments only when the detail makes sense right beside the code

Avoid copying the same instruction into several places. Duplicates age badly. Keep the full rule in one place, then use local notes only for local exceptions.

That setup is easy to scan. A new teammate can check the top-level file first, then the folder they are working in, and get moving without digging through old task history.

How to add prompt notes step by step

Teams often start writing repo notes after one messy task, then paste too much into the repo. That creates clutter fast. A smaller approach works better: write only what a person or coding assistant will need again.

Start with one repeated problem from recent work. Maybe the assistant keeps putting database helpers in the wrong folder. Maybe it writes tests that ignore your existing fixtures. If the issue happened once, wait. If it happened twice, it probably deserves a note.

Keep the process simple. Pick one recurring problem, not a whole policy. Write the note in plain language. Name the exact folder, file type, command, or review step it covers. Then test the note during the next real task. If it prevents the same mistake, keep it. If nobody uses it, trim it or delete it.

A short example usually helps more than extra explanation. "In services/billing, keep HTTP handlers thin. Put pricing logic in internal/pricing." That gives clear direction and a clear location. A long paragraph about clean architecture does less.

Be precise about boundaries. If a rule applies only to migrations, say that. If it matters only during code review, say that too. Repo notes fail when they sound universal but only fit one corner of the codebase.

After the next real task, read the note again with fresh eyes. Did it prevent confusion? Did people still need follow-up messages? If they did, rewrite it until a new teammate could act on it without a meeting.

That is the whole cycle: notice a repeated snag, write the smallest useful rule, put it in the right place, and check it in real work.

A simple example from a small team

Imagine a small product team with two services: a customer API and an internal admin app. Bugs often touch both. A fix might start in the API, then end with a small admin change so support staff can see a new status or retry a failed job.

The team keeps repo notes, but only for things people need again and again. They do not keep a diary of every bug. They keep short instructions that help the next person start quickly and avoid common mistakes.

In the API folder, they keep a note with the test commands they actually run before a commit. It also says where logs live in local development and in production. That saves time because nobody has to guess whether a failed request will show up in the app logs, worker logs, or gateway logs.

In the admin app folder, they keep another note about naming new endpoints. It explains how the team names routes, background jobs, and status fields so the API and UI stay consistent. A new teammate can open that note and follow the same pattern instead of inventing a new one.

Those notes stay short because short notes get read. A useful note might include the unit test command for one service, the smoke test command across both services, the first place to check logs for auth, jobs, or webhooks, and the rule for naming endpoints and response fields.

What the team leaves out matters just as much. They do not paste old ticket history, chat summaries, or long explanations about why bug #184 happened three months ago. If that detail will not help with the next similar task, it does not belong in repo notes.

That is the difference between useful guidance and stale clutter. Reusable instructions stay close to the code. One-off history stays in tickets, commits, and issue trackers.

Mistakes that make notes go stale

Notes age quickly when they describe one person's habits instead of the team's actual workflow. That happens all the time. Someone writes a reminder in their own shorthand, and everybody else has to guess what it means.

A note like "use the usual review prompt" works for the person who wrote it. It fails for a new hire, a contractor, or even the same person three months later. If a note depends on private context from Slack, memory, or a meeting, it is already too weak to keep.

Old commands are another common problem. Teams switch package managers, rename scripts, move folders, or replace one AI coding tool with another. The note stays behind and keeps telling people to run commands that no longer work.

That kind of breakage spreads fast. People stop trusting the file, and then they stop reading it. One wrong command can do more damage than five missing notes.

Files also go stale when people mix stable rules, temporary tasks, and old decision history in one place. Those belong in different tools. A repo note should tell people what to do now when they touch the code again.

If the file starts reading like a policy manual, meeting log, and to-do list at the same time, nobody will know what is still active. Commit history already keeps the past. Task trackers already hold short-lived work. Repo notes should keep only the instructions that repeat.

Another mistake is writing too much before anyone has used it. Teams sometimes try to document every edge case up front. Most of those notes never get tested in real work, so they sit there and rot.

A better rule is simple: write the note after a task repeats and after the team agrees on the right way to do it.

Stale notes usually show the same signs:

• only the author can explain what they mean
• the command fails on a fresh setup
• the file includes temporary tasks or decision logs
• the workflow in the note no longer matches how the team actually works

Small teams feel this sharply. They may move fast for months, then lose time every week because one dusty note keeps sending people down the wrong path. Short, tested, current notes beat a big file full of half-true instructions every time.

A quick checklist before you commit notes

Most bad repo notes fail for one reason: they only make sense to the person who wrote them. If a new teammate cannot follow the note on a normal Tuesday without asking what you meant, the note is not ready.

A short review before commit saves cleanup later and keeps repo notes useful.

Read the note as if you joined the team this week. Does it explain enough to act without extra chat messages or private context? Ask whether the task happens more than once. If the note only matters for a one-off fire drill, keep it out of the repo and put it in the ticket or postmortem. Re-run every command and path. If nobody checked them recently, they are guesses, not instructions. Then cut dates, status updates, and old reasoning that no longer changes what someone should do today.

That check matters more than teams admit. A note that tells people to run a script from the wrong folder wastes time fast, and after one bad command people stop trusting the rest of the docs.

A simple test works well: ask one person who did not write the note to use it. If they pause and ask, "Which service is this for?" or "Does this path still exist?" the note needs another pass. You do not need polished prose. You need directions that work.

This also helps with stale task history. Repos often collect lines like "temporary workaround for last month's deploy issue" or "keep this until migration ends." Those lines age badly. If the note does not help someone complete a repeat task now, delete it or move it to the place where project history belongs.

Good notes feel plain. They tell someone what to do, where to do it, and what success looks like.

What to do next

Start with the workflow that wastes the most time each week. Pick the one that keeps causing repeat questions in chat or review comments, whether that is how to run tests before a merge, how to name migration files, or what format your team uses for AI coding instructions.

Write a note that fits on one screen. If it grows into a long explainer, cut it down. Repo notes work best when someone can read them in the middle of a task and move on.

A simple structure is enough: name the task, list the few rules that rarely change, add one short example from the codebase, and assign one owner for updates.

Then test the note during live work. Ask one teammate to use it on a normal task without extra help in chat. Watch where they pause. If they still need to ask basic questions, the note is too vague. If they finish with fewer interruptions, keep that version and improve it later.

Set a light review habit so the note does not turn into stale history. One owner is enough. That person can check the note after a release, after a tooling change, or once a month. Most notes do not need constant editing. They just need someone to remove wrong steps before they confuse the next person.

A small team can start today. If deploy steps keep drifting, add a short note beside the deployment scripts. If code review prompts vary from person to person, add one shared note near the review tools. Keep each note close to the code it affects.

If your team wants help designing that kind of system, Oleg Sotnikov at oleg.is advises startups and small teams on practical AI-first engineering workflows. That can include where repo notes should live, how they fit into code review and automation, and how to keep them short enough that people actually use them.

If you only do one thing today, fix the workflow that keeps interrupting people. One clear note often saves more time than another meeting.