PRD System for Claude Code

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.

The Problem

A fresh Claude Code conversation does not automatically contain every decision from earlier work. Saved conversations can be continued or resumed, but their active context still has limits.

Claude Code supports --continue and --resume for saved history. A maintained task document complements that recovery: it records accepted requirements, decisions and next steps in a compact source that can be checked against the code.

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 is the workflow using optional Justfile recipes. These recipe names belong to a local implementation; they are not built-in commands. The Getting Started section below provides a plain-shell setup that works without a downloaded repository or Justfile.

# 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

An optional Justfile can provide the following interface. Implement the recipes in your own workspace before running these commands; the file-based approach itself does not require just:

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

Keep task folders outside application repositories. If you publish a reusable template, exclude the task directory from that template repository and check what is tracked before sharing it. A git-ignore rule prevents accidental additions; it is not an access-control mechanism.

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: A session log explicitly updated after each session
• 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

# Use a new example task directory; mkdir fails if it already exists.
mkdir -p ~/prd/prj/example-project
mkdir ~/prd/prj/example-project/example-task && (
  cd ~/prd/prj/example-project/example-task || exit 1

  cat > task.md <<'TASK'
# Example task

## Goal
Describe the behavior to implement.

## Acceptance criteria
- State observable checks for a completed result.

## Constraints and context
- Record relevant versions, references and boundaries.
TASK

  cat > sessions.md <<'SESSIONS'
# Session log

## Progress
- No implementation yet.

## Decisions
- Record decisions and their reasons here.

## Next steps
- Review the task requirements before making changes.
SESSIONS
)

# From your application repository, start your installed Claude Code.
# Ask it to read these task.md and sessions.md files, then summarize
# the requirements before proceeding. No fork, clone or upstream is required.

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

Create the local workspace and the two starter files shown above, adapt the headings to one real task, and explicitly update the session log after each working session. Add automation only when the manual workflow is useful.

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