Hello Curious Coders,

You finish a good session. The feature works, the warnings are gone, the tests pass. You commit, you push, and you close the laptop feeling checkpointed.

The next morning you open a fresh conversation and the agent has no idea why the dictionary got split into answers and guesses. You explained that yesterday. You explained it twice, and then talked through the plan before a single line of code got written.

None of that reasoning is in the repository. It lived in the conversation, and the conversation is gone.

The code was checkpointed. The project wasn’t.

That gap is what this module is about. Checkpointing sounds like a Git topic, but with AI work, Git is only one part of the story. The real question is simpler and more uncomfortable: where does your project actually live?

Three Places the Truth Can Live

Bruce opens the module by refusing the easy answer.

“There are three different sources of truth. There’s the code base itself, there’s the context that we use to describe the code base and give Claude work to do, and then there’s the source code repository.”

• Bruce Tate

The first source is familiar: the code base itself, the files on disk, the thing your editor shows you, the thing that compiles.

The second one is newer and less stable. It is the agent context: everything the agent currently believes about your project, including the architecture you described, the constraint you added halfway through, and the correction you made when it named a function badly.

That context is real state. It steers the code that gets written, even though it disappears when the session ends.

The third source is the repository. In class, Bruce talks about GitHub, but the hosting service is not the point. The point is the durable shared record.

Most of us treat the repository as a backup of the code base. With AI, that model is too small. Commit the code and you have only synced one piece. The other two can drift quietly, and you usually discover the drift when the next session starts cold.

The Jump You Already Made Once

Here is the reassuring part: you have already made this mental shift, just for a different artifact.

Think about how you learned to program. At first, the code was whatever was on your screen. The editor felt like the program. Then you got better about saving, and the code became the files on your file system.

At some point, usually after losing work or joining a team, something clicked: the file on disk is not the source of truth. It is a working copy. The code is an extension of the repository.

That is a real jump, and every developer eventually makes it.

Now look at prompts and guidance. They start in the agent, because that is where the conversation is. As the models get more capable, more of your thinking moves into that window. You describe the architecture. You explain the next slice. You correct assumptions. You develop a plan together.

Then you learn that shorter conversations work better, so you start saving prompts and plans as files. That is better, but it is still the middle of the story. It is the flat-files stage, not the repository stage.

Bruce names the destination plainly:

“The whole application, the prompting and the guidance both, live in the repo.”

• Bruce Tate

And then he says the sentence that should change how you work:

“The question, where’s the state? It lives in the repo. That’s where you have to park your head. That’s where your mental model has got to be.”

• Bruce Tate

Prompts follow the same path code did. They begin in the agent as transient context, move to the file system as something you can reuse, and belong in the repository as part of the application.

What Goes Where

Once guidance belongs in the repo, sorting it gets easier, because the sorting question is just: how often will I need this?

One-time, project-specific information belongs in claude.md: the architecture of this application, the domain rule you had to correct, the current phase of development, and where the plans live. It is true about this project and nothing else, so it travels with this project.

Repeated-use elements belong in reusable infrastructure: agents, scripts, skills, and hooks. Those are the how-to pieces. They should not describe your Wordle app specifically. They should describe a technique you expect to use again in the next app.

There is a second distinction, and it matters just as much. Project guidance does not all change at the same speed.

The stable tier contains architecture, conventions, long-term decisions, and pointers to where important things live. The volatile tier contains plans: the feature you are building this week, the slice you want the agent to implement next, and the temporary notes you will delete or replace once the work lands.

Mixing those two makes both worse. Stable guidance becomes noisy, and plans start pretending to be permanent. Keep the stable tier as structure. Keep the volatile tier as documents the stable tier points at.

Put the Next Plan in the Repo

You can start this without building new infrastructure. The technique is simple: before the agent writes code, put the next plan in docs/plans/current.md.

Before, the plan lives only in chat:

Implement the split between answers and guesses. Keep the existing validation behavior. Add tests for duplicate guesses.

That works until the conversation disappears.

After, the same plan lives in the repo:

# Current Plan

Implement the split between answers and guesses.

Constraints:

- Keep the existing validation behavior.
- Add tests for duplicate guesses.
- Update only the dictionary-loading path.

Then begin the next session by asking the agent to read docs/plans/current.md before coding.

The rule is this: if the next step would be expensive to re-explain, it belongs in the repo before implementation starts. Once the work lands, commit the code and either update, replace, or delete the plan.

None of this is exotic. It just moves state out of the places where it disappears and into the place where it can travel.

The Repository Is the Project

The layering idea has not changed. Long-term guidance, reusable technique, project architecture, and current plans are all layers in the way you collaborate with the agent.

What changes is that those layers need homes. The agent conversation is a useful workbench, but it is not where the project lives. The local file system is a step forward, but it is still not the final source of truth.

The repository is.

Once you park your mental model there, checkpointing stops being a Git chore at the end of the day. It becomes the practice of keeping the code, the agent context, and the repository aligned.

If guidance lives in the repo, it needs a real home and a real structure. That is what we build next: agents.md, usage rules, and claude.md as the glue that connects prompting, plans, and the repository.

— Paulo & Bruce