How to Checkpoint Code Projects with AI Agents - Save Your Work, Keep Projects on Track, and Reduce Rework

DISCLOSURE: If you buy through affiliate links, I may earn a small commission. (disclosures)

I've been Power Coding with Claude Code the past couple months and have been reading up on best practices for working with AI agents.

One of the most common pitfalls I see from newcomers is their painful experiences bricking their systems and losing all their work.

The solution to this is simple - add checkpoints. Here I'll explain the various kinds of checkpoints that are useful in code projects and how to implement them.

What is a checkpoint?

A checkpoint is a snapshot of your progress at a point in time. This is useful for saving system progress so that if (and when) you implement a bug, you always have a good state to rollback to.

There are two kinds of checkpoints I think are useful when working with AI agents:

Code checkpoints
Project checkpoints

A code checkpoint is like a save in a game

A code checkpoint is similar to a save in a video game. It's a save point you can load back into at a later date if a problem occurs and you want to boot up a "safe" copy.

This is useful as there will be bugs so sometimes it's easiest to roll back and start over (perhaps with a new prompt) than try to fix what happened.

With code checkpoints, you only need to rollback to your last save - not start the whole game over, losing hours or even days of work.

A project checkpoint is like a quest tracker

A project checkpoint is more similar to a quest list and tracker.

It's useful for understanding where you are in the game as a whole - what the goal is and what your progress is towards that goal.

This is useful for AI because they hallucinate - the longer they work on something and the more context they get, the greater their chance to start diverging from the initial prompts. By providing them with project checkpoints we allow them to focus on one thing at a time and lower the rate of them going off track.

This is particularly useful with AI agents where the big unlock is allowing them to work independently on large tasks for an extended period of time. If they go off track all the time then the work they produce will be useless, rendering the benefits moot.

How to implement code checkpoints

Some IDEs and AI tools have checkpointing built in so if they have that you should use it. But you should also use another version of checkpointing that is more powerful and gives you more control.

This is a checkpointing system that software engineers have been using effectively for decades: version control. Git is the current leading version control system so you should start with that - it works on every platform and most IDEs have built-in tools for it so you shouldn't have to install / configure much.

In its simplest form, git allows you to construct branches of saves. At any time you can create a new save, create a new branch of saves, or load an old save. These branches can be merged together later which is useful if you have multiple people working on different parts of a project and want all of that work to be brought together.

Some game terms to git equivalents:

Save -> commit
Load -> checkout
Branch -> branch

An intro to git is beyond the scope of this post but there are plenty of guides online that can get you started.

As for how I use git in my AI workflows, I like to follow the Power Coding philosophy of being an active contributor with the AI. I find this leads to better outcomes and fewer bugs which leads to more efficient coding overall.

My checkpointing system goes like this:

Give AI an atomic task
Review the code and make changes
If I like it, checkpoint (commit) the code
- If I'm working in a team - I might submit a PR here to get it merged into the main branch
Continue to the next task

How to implement project checkpoints

So code checkpoints help us with saving progress on all our individual tasks but we still need some way to think about our project as a whole - after all each task should be helping some project move to completion.

This is especially important for AIs due to the hallucination issue and how much more context is required for a project as a whole vs a single task within it. When hallucinations happen, we'll typically need to create a new AI session to reset them to the important context so if you don't have a project checkpoint available it's going to take a lot of prompts and tokens to onboard the new AI to the appropriate context.

This is where project checkpoints come in. They're basically going to be quest trackers where we lay out goals and progress so any AI that comes in can understand what they need to do, what's already been done, and what they should work on next - WITHOUT re-prompting everything.

I implement project checkpoints with 2-3 docs depending on the size of the project.

An RFC for sufficiently large projects - spanning many tasks, people, and/or teams
A Task Description markdown file - Describing the context and work that needs to be done
A Task Tracking markdown file - Notes the AI keeps about what it needs to do and what progress it's made

RFCs are useful for keeping projects and humans on track

If you've ever worked at a company building software, you've probably read and written RFCs.

An RFC (Request for Comments) is basically a proposal to make some change - it could be a large feature, a new product, or a large tech migration.

They'll usually contain things like:

The business context - What problem we're trying to solve and why it matters
The solutions you propose
A general plan for how to make that happen

Not every change is going to need a full RFC but larger changes that need to work across multiple tasks and / or teams often benefit from them as they can get people aligned on what we're trying to build.

Knowing what you want to build and how is crucial for getting the most out of AI because that's how you're going be able to give it better tasks, prompts, and reviews to reduce rework.

This RFC is basically the primary project checkpoint for humans - where we can see what we're trying to do, our progress, and what's next. If there's ever a catastrophic problem with AI or our codebase, we can always fall back on the RFC to get back on track.

Task Description files allow for more detailed, reusable AI prompts

Most people prompt AI by typing into the chatbox. That works but is hard to systemize. If you spin up a new AI you basically need to retype everything you already said.

By instead writing our prompt in a file, we immediately get the ability to link that prompt to any new AI we spin up. This means that any extra details you provide aren't wasted or missed when you start a new session.

I personally find myself typing up more descriptive prompts when I write in a file because it allows me to review and iterate on what I've said. It also gives more room to provide examples if I have them which is a large boost to an AI's ability to one-shot a task.

Task tracking files help the AI stay on track

If the task description is the quest description, the task tracking file is how the AI tracks its progress.

I usually make the AI write up its plan and track its progress in a new file. This will allow it to summarize what it understands and format its tracker how it wants. This gives me another opportunity to review what it thinks it should do and course correct if I see something wrong.

With the task description and tracking files in place, I'm never worried about spinning up a new AI session if the old one gets stuck - the new AI can catch up on what we're doing and where we are and start chugging away on the next task.

How I build software with AI agents and checkpointing

So that's a lot about the individual methods of checkpointing and I want to bring this all back together into a cycle I use to build with AI.

The flow starts with:

Create an RFC at the beginning of the project to plan and track overall progress
- If the task is small and self contained, I may skip this step and just put the plan in the Task Description

For each task I'm going to work on:

Create a Task Description markdown file - often named something like hamy-TICKETID
Make the AI create its own Task Tracking markdown file - named smth like agent-TICKETID
Iterate with AI through the task:
- I give AI the Task Description and Task Tracker
- AI codes
- I review and change
- Commit / push when I'm happy with it
- AI updates its tracking doc

When I'm feeling spicy, I'll sometimes try to parallelize tasks. That's been hit or miss for me but I feel like this capability is close on the horizon.

AI is an incredible tool but we're still figuring out the best ways to work with it. I've found that a lot of the best practices for getting the best out of AI are similar to the best practices for getting the best out of software engineers. Vibe engineering / power coding takes more active work short-term than vibe coding but tends to end up with better outcomes and less rework debugging / fixing problems so ends up with higher throughput long term.

If you have an AI collaboration process that's working for you, I'd love to hear about it! Can comment below or message me on one of my socials.

If you liked this post you might also like:

Want more like this?

The best way to support my work is to like / comment / share for the algorithm and subscribe for future updates.