Artificial Intelligence

PRD System for Claude Code

Maintaining Context Between Sessions

TL;DR: I created a simple file-based system to manage development tasks with Claude Code. It helps maintain context across sessions using markdown files. Check it out on GitHub.

The Problem

When working with Claude Code, there's a challenge: Claude Code doesn't persist conversation history between sessions.

You're working on a feature, making progress, and understanding the codebase together. Then you close your terminal. Next day when you start Claude Code again, it has no memory of previous conversations - what you were building, what decisions were made, or what's left to do. You need to re-explain the context each time.

I wanted to find a way to make this smoother.

The Solution: A Personal PRD System

I built a lightweight, file-based system that lives in ~/prd. Every task gets two simple files:

  • task.md - The requirements, goals, and context
  • sessions.md - A running log of progress

Here's the workflow:

# Create a new task
cd ~/prd
just new my-project user-authentication

# Edit the requirements (opens in your text editor)
just edit my-project user-authentication

Then, in your actual project:

cd ~/code/my-project
claude

# Load the task context:
"Read ~/prd/prj/my-project/user-authentication/task.md and sessions.md
Give me a summary and let's continue from where we left off"

Claude now knows:

  • What you're building and why
  • What was accomplished in previous sessions
  • What decisions were made
  • What's left to do

When you're done working:

"Update ~/prd/prj/my-project/user-authentication/sessions.md with today's progress"

That's it. No databases, no cloud services, just markdown files.

Why This Approach Works

1. Separation of Concerns

PRD docs live in ~/prd, completely separate from your code. This means:

  • No clutter in your actual repositories
  • One central place to track tasks across all projects
  • Easy to back up, version control, or sync

2. Persistent Context

Every work session builds on the last. Claude reads the entire history and can pick up where things left off. Less time spent re-explaining context.

3. Simple Automation

A Justfile provides commands to manage tasks:

just new PROJECT TASK      # Create new task
just edit PROJECT TASK     # Edit requirements
just list                  # See all your tasks
just work-on PROJECT TASK  # Get instructions for working on it
just archive PROJECT TASK  # Archive when done

4. Private by Default

The system is designed to be forked. Your projects stay on your machine (git-ignored), but you can pull updates to the system itself. Only example projects are version controlled.

Real-World Example

Here's how it might be used for adding OAuth authentication to a side project:

Day 1:

cd ~/prd
just new personal-blog oauth-authentication
just edit personal-blog oauth-authentication
# Add requirements, goals, technical constraints

In the actual project:

cd ~/code/personal-blog
claude

"Read ~/prd/prj/personal-blog/oauth-authentication/task.md and sessions.md
Help me implement OAuth authentication with GitHub and Google providers"

Together with Claude, we research OAuth flows, choose a library (NextAuth.js), and start implementing the GitHub provider.

End of day:

"Update ~/prd/prj/personal-blog/oauth-authentication/sessions.md

Accomplished:
- Researched OAuth2 flows and security best practices
- Chose NextAuth.js as authentication library
- Implemented GitHub OAuth provider
- Set up session management with HTTP-only cookies
- Created login button component

Decisions:
- Using NextAuth.js instead of custom implementation (less maintenance)
- Storing sessions in cookies, not localStorage (more secure)
- 7-day session expiry with sliding window

Next steps:
- Add Google OAuth provider
- Implement logout functionality
- Add error handling for failed authentication
- Write tests for auth flow

Status: In Progress"

Day 2:

cd ~/code/personal-blog
claude

"Read ~/prd/prj/personal-blog/oauth-authentication/task.md and sessions.md
Show me where we left off"

Claude instantly has:

  • The full context of the authentication feature
  • What was implemented yesterday
  • The decisions that were made (and why)
  • Exactly what needs to happen next

Much less time spent on catch-up.

Day 3 (a week later):

Even after a break, the same command loads all context immediately. No need to remember what you were doing or why you made certain choices.

What Makes This Different

There are other ways to give Claude context (like CLAUDE.md files in repos), but this system takes a different approach:

  • Task-focused: One folder per task, not per project
  • Session memory: Automatic history of work done
  • Cross-project: Manage all tasks in one place
  • Resumable: Pick up easily after days or weeks

The Technical Details

The system uses:

  • Just - A command runner (like Make, but simpler)
  • Markdown - Simple, readable, version-controllable
  • Git - Only for system files, not your tasks (unless you want to)

The structure is straightforward:

~/prd/
├── README.md       # Documentation
├── TEMPLATE.md     # Template for new tasks
├── Justfile        # Automation commands
└── prj/            # Your projects (git-ignored!)
    └── {project}/
        └── {task}/
            ├── task.md      # Requirements
            └── sessions.md  # Work log

Getting Started

# Install prerequisites
brew install just
brew upgrade claude-code

# Fork and clone
git clone https://github.com/YOUR-USERNAME/prd.git ~/prd
cd ~/prd

# Set up upstream for updates
git remote add upstream https://github.com/vpetreski/prd.git

# Try the example
just list
just work-on acme-app user-authentication

Check out the full documentation on GitHub for more details.

What's Next

I'm using this system for my work with Claude Code. Some ideas for future improvements:

  • Templates for common task types (bug fixes, features, refactors)
  • Better search across all tasks
  • Integration with Linear/Jira to pull in issue details
  • Statistics and insights (time spent, completion rates)

For now, it's helping maintain context better. Load, work, save, repeat.

Try It Yourself

If you work with Claude Code regularly, this system might be useful. Fork the repo, create a task, and see if it fits your workflow.

The goal: spend more time building, less time re-explaining context.

Links:

Have questions or suggestions? Open an issue on GitHub or reach out.

Read more