What belongs beside your code? Choosing the context that travels with a project

Open a project you have not touched in three months. The folder tells you what is there: a src/ directory, a test suite, a build config. It does not tell you why the cache layer was removed, which library you tried and dropped, or what your assistant must never touch in the migrations folder.

That missing "why" used to live in your head. Now you code with an AI assistant, and a fresh session knows only what it can read. So the question is no longer just "what is in the repository?" It is "what context should sit beside the code, so the next person or the next session starts from the right place?"

This article gives you a clear answer. You will leave with a list of context worth keeping next to your code, a list of things that must never travel with it, and a short review routine to run before you share anything.

A folder shows what, not why

Source code is the result of many choices. The choices themselves are rarely in the code.

Think of the situations you already know:

• A new session suggests the approach you rejected last week, because nothing says you rejected it.
• A teammate asks "why is it done this way?" and the answer is in a chat you cannot find.
• You switch laptops mid-refactor and spend the first hour rebuilding your own plan.

Git history helps a little. A commit message says what changed, and sometimes why. But it is spread across hundreds of entries, and nobody reads it before starting work. Context works best when it is small, current and in a known place.

The context that should travel

Three kinds of context earn a place beside your code. Each has a different job.

Project instructions

These are the standing rules for anyone working on the project, human or assistant. How to run the tests. Which folders are generated. The conventions you enforce. Claude Code reads CLAUDE.md; Codex and many other coding agents read AGENTS.md. For a full walkthrough, see writing project instructions your assistant follows.

Decisions and notes

This is project memory: what you decided, what you rejected, and what is still open. A short entry such as "We store dates as UTC strings, not timestamps, because the export format needs them" saves a long debate later. The companion guide on project memory for AI coding covers what to write and when.

Selected conversations

Some AI sessions are worth keeping: the one where you worked out the data model, or the debugging session that found a race condition. Most are not. Keep the few that explain a decision you would otherwise have to rediscover, and let the rest go.

A layout that keeps all three together can look like this:

my-app/
├── CLAUDE.md                 # instructions for Claude Code
├── AGENTS.md                 # instructions for other agents
├── src/
├── tests/
└── .prjcontext/
    ├── instructions/         # longer instruction files, if you need them
    ├── memory/
    │   ├── decisions.md
    │   └── open-questions.md
    └── sessions/
        └── 2026-09-data-model.md

Plain Markdown files are enough. The point is a predictable place, so people and assistants know where to look.

The context that should never travel

Some context feels useful in the moment and is harmful once it leaves your machine. Four groups stay out.

Passwords, keys and tokens. .env files, private keys, cloud credentials, API tokens pasted into a transcript. If a secret ends up in a shared session file, treat it as exposed and rotate it. The guide on keeping secrets out of your AI context goes deeper.

Private paths and machine details. Lines like /Users/anna/clients/acme-private/ reveal client names, folder structures and usernames. They also break on every other machine. Use paths relative to the project root.

Unrelated personal details. Transcripts pick up everything: a note about a doctor's appointment, a colleague's name, a side project. None of it helps the project. Cut it.

Global assistant settings. Your assistant's user-level configuration, such as a personal CLAUDE.md in your home folder, holds your preferences across every project. It may mention other clients or tools. It belongs to you, not to one repository.

Here is a quick way to sort borderline items:

Select deliberately, then review

Context does not become useful by collecting everything. It becomes useful by choosing. A folder full of every transcript is as hard to read as no transcripts at all, and much riskier to share.

Make selection a habit, not a cleanup job:

1. At the end of a session, ask yourself one question: would the next person need this to avoid a wrong turn? If yes, save a short note or the session. If no, move on.
2. Trim before saving. Remove the dead ends that taught nothing, the pasted logs, and any output that contains values from your environment.
3. Rewrite, don't just paste. Two lines in decisions.md often beat a forty-message transcript.

Then, before you share, run a review. This checklist takes a few minutes:

• ☐ Search the context files for key, token, secret, password, BEGIN and @ (emails).
• ☐ Search for absolute paths (/Users/, /home/, C:\).
• ☐ Read every session file you are about to share, top to bottom.
• ☐ Remove names of clients or people who have nothing to do with this project.
• ☐ Confirm no user-level assistant settings were copied in.
• ☐ Check the list of files that will be uploaded, not just the files you remember adding.

A before and after makes the difference clear. Before:

## Local setup
Copy the env from /Users/anna/secrets/acme.env and use the admin
token sk-live-... for testing. Ask Tom (the Acme CTO) if it fails.

After:

## Local setup
Copy `.env.example` to `.env` and fill in the values from the
team password manager. Tests use the sandbox key, never a live one.

Same purpose, nothing private, and it works on any machine.

Keep it small enough to stay true

Context goes stale. An instruction file that still says "we use the old router" is worse than none, because an assistant will follow it.

A few habits keep it honest:

• Date decision entries, and mark old ones as superseded instead of deleting them.
• When a session changes a rule, update the instruction file in the same sitting.
• If a note has not been useful in months, move it to an archive section or remove it.

Short, current context gets read. Long, stale context gets ignored or, worse, obeyed.

How PrjLab handles this

We built PrjLab around this split between what travels and what stays.

• A repository holds your files plus context in .prjcontext/instructions/, .prjcontext/memory/ and .prjcontext/sessions/, and CLAUDE.md and AGENTS.md at the project root are recognised too. Nothing ends up in a session folder unless you put it there.
• prj status shows exactly what would be captured before you run prj push, so the review step has a concrete list.
• The CLI skips obvious secrets such as .env files, key files and credential folders, plus anything in .gitignore or .prjignore. It is a safety net, not a complete secret scanner, so your own review still matters.
• Global assistant folders, other projects and machine credentials are never scanned.
• The prj CLI is open source (MIT), so you can read what it captures. Access to hosted repositories is controlled by the service: repositories are private by default, and you share by handle as a reader or writer.

Frequently asked questions

Is this a replacement for git? No. PrjLab sits beside git. Keep using git for your code history; use a context folder for the reasoning around it.

Should I commit my .prjcontext/ folder to git too? That is your choice. Instructions and decisions are often fine in git. Review session files with more care, since transcripts collect more than you expect.

What if a secret already went into a shared transcript? Remove it from the file, then rotate the secret. Deleting the text does not undo the exposure.

How many sessions should I keep? There is no right number. Keep the ones that explain a decision someone would otherwise have to rediscover.

To try this with your own project, follow the getting-started guide.