Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/vpetreski/prd

PRD System for Claude Code - Manage development tasks with Product Requirements Documents
https://github.com/vpetreski/prd

ai claude claude-code prd

Last synced: 3 months ago
JSON representation

PRD System for Claude Code - Manage development tasks with Product Requirements Documents

Awesome Lists containing this project

README 

          
# PRD System for Claude Code



> **📝 Read the full article:** [PRD System for Claude Code](https://vanja.io/prd-system-for-claude-code/)



A lightweight, file-based system for managing tasks across multiple projects using Product Requirements Documents (PRDs), designed specifically for **Claude Code**.



## What This Is



This system helps you organize and track development tasks across different projects with **Claude Code** as your AI pair programmer. Each task gets its own folder with:

- A **task.md** file containing requirements, goals, and context

- A **sessions.md** file tracking your work sessions and progress



This approach keeps your tasks organized, makes it easy to resume work after interruptions, and provides a clear history of decisions and progress. Claude Code reads these files to understand your project context and help you implement features efficiently.



## How It Works: Two Contexts for Claude Code



Working on a task involves using **Claude Code in TWO different contexts**:



### Context 1: Planning & Architecture (in ~/prd)



**Location:** `~/prd` directory

**Role:** Product/Architecture/Orchestration

**Tools:** `just` commands + `claude`



**What you do here:**

- Create and manage tasks (`just new`, `just edit`)

- Work with Claude Code to refine requirements from external sources

- Have Claude help you create detailed task.md files

- Generate workflow.md guides for complex/multi-repo tasks

- Plan implementation strategies

- Track high-level progress



**Example:**

```bash

cd ~/prd

claude

# "Help me create a task.md for migrating our auth system.

#  Here are the requirements: [paste external requirements]"

```



**Think of this as:** The product/architect side where you define WHAT needs to be done and HOW to approach it.



### Context 2: Implementation (in your actual code repos)



**Location:** Your actual project directories (e.g., `~/code/my-project`)

**Role:** Engineering/Implementation

**Tools:** `claude` (reading PRD files for context)



**What you do here:**

- Run Claude Code in your actual codebase

- Reference the PRD files you created in ~/prd

- Have Claude help with actual implementation, debugging, testing

- Update sessions.md to track what you accomplished

- Make commits, run tests, deploy code



**Example:**

```bash

cd ~/code/my-project

claude

# "Read ~/prd/prj/my-project/auth-migration/task.md and sessions.md

#  and help me implement the JWT token changes"

```



**Think of this as:** The engineering side where you DO the actual work.



### The Complete Flow



1. **Plan in ~/prd** → Work with Claude to create task.md and workflow.md

2. **Code in your repos** → Work with Claude to implement, referencing PRD files

3. **Track in ~/prd** → Have Claude update sessions.md with progress

4. **Repeat** → Continue cycling between planning and coding as needed



**Key Insight:** You're working with Claude Code in both places, but for different purposes:

- **~/prd = Product thinking** (requirements, strategy, planning)

- **~/code/project = Engineering thinking** (implementation, debugging, testing)



## Requirements



To use this system, you need:



- **[Claude Code](https://claude.com/claude-code)** - The official CLI from Anthropic

  - Install: `brew upgrade claude-code` (macOS) or download from [claude.com/claude-code](https://claude.com/claude-code)

  - Version: Latest recommended

- **[Just](https://github.com/casey/just)** - Command runner for automation

  - Install: `brew install just` (macOS) or see [installation guide](https://github.com/casey/just#installation)

- **Git** - For version control and updates

- **Terminal/Shell** - bash, zsh, or similar



## 🔒 Privacy Model



**Your projects stay private.** This repository is designed so you can:

- Fork it to your own GitHub account

- Track your peronal/work projects locally

- Pull updates to the PRD system without exposing your work



**How it works:**

- All your projects live in `prj/` directory

- The `prj/` folder is **git-ignored** (except for the example project)

- Only the PRD system files are version controlled (README, Justfile, TEMPLATE.md)

- When you pull updates, you get new features without conflicts with your projects



**Example project:** The `prj/acme-app/` directory is the only exception - it's version controlled to serve as documentation. You can delete it anytime.



## 🚀 Installation



### Prerequisites



Before installing, make sure you have the requirements (see Requirements section above):



```bash

# Install Claude Code (required!)

brew upgrade claude-code  # macOS

# Or download from: https://claude.com/claude-code



# Install Just (required!)

brew install just  # macOS

# Or see: https://github.com/casey/just#installation



# Verify installations

claude --version

just --version

```



### Setup Steps



**Important:** This system is designed to work in `~/prd` directory. Clone it there:



```bash

# 1. Fork this repository on GitHub to your own account

#    Click "Fork" button at https://github.com/vpetreski/prd



# 2. Clone YOUR fork to ~/prd (not just any directory!)

git clone https://github.com/YOUR-USERNAME/prd.git ~/prd

cd ~/prd



# 3. Set up upstream to pull system updates

git remote add upstream https://github.com/vpetreski/prd.git



# 4. Verify setup

git remote -v

# Should show:

# origin    https://github.com/YOUR-USERNAME/prd.git (fetch/push)

# upstream  https://github.com/vpetreski/prd.git (fetch/push)



# 5. Test it out!

just list

# Should show the example acme-app project

```



**Why ~/prd specifically?**

- All documentation examples use `~/prd`

- Justfile commands assume this location

- Makes it consistent across your machines

- Easy to remember and navigate to



### Repository Permissions



**You can:**

- ✅ Fork this repo to your own GitHub account

- ✅ Clone your fork to ~/prd

- ✅ Create unlimited private projects (automatically git-ignored)

- ✅ Pull updates from upstream (vpetreski/prd) anytime

- ✅ Push to your own fork (if you want to sync across your machines)

- ✅ Customize your fork however you like



**Only the original author (vpetreski) can:**

- ❌ Push updates to the upstream repository (vpetreski/prd)

- ❌ Release new versions of the PRD system



**This means:**

- Your projects stay private on your machine

- You get system updates by pulling from upstream

- You can't accidentally push to the upstream repo (you don't have permission)

- Your fork is yours - push to it if you want your projects on GitHub



### Pulling System Updates



When new features are released:



```bash

cd ~/prd



# Pull latest system improvements

git fetch upstream

git merge upstream/main



# Your projects are safe! Only system files get updated:

# - README.md (new documentation)

# - Justfile (new commands)

# - TEMPLATE.md (improved template)

# - prj/acme-app/ (updated example)

#

# Your projects in prj/* remain untouched!

```



### Optional: Sync Your Projects Across Machines



If you want to sync your own projects via GitHub:



```bash

# Option 1: Push to your fork (WARNING: This makes your projects public!)

git add prj/my-project  # This will fail - prj/* is ignored!

# You'd need to modify .gitignore first



# Option 2 (Recommended): Use a separate private repo for projects

cd ~/prd/prj

git init

git add .

git remote add origin https://github.com/YOUR-USERNAME/prd-projects-private.git

git push -u origin main



# Now ~/prd system updates and ~/prd/prj are separate repos!

```



## Quick Start



Ready to try it? Here's the two-phase workflow:



### Phase 1: Planning in ~/prd (Product/Architecture)



```bash

# Create task structure

cd ~/prd

just new my-project user-login



# Option A: Write requirements manually

just edit my-project user-login  # Opens in text editor



# Option B: Work with Claude to refine requirements

cd ~/prd

claude

# "I need to create a task for user login with OAuth support.

#  Here are the requirements: [paste requirements].

#  Help me create a comprehensive task.md file."

```



### Phase 2: Implementation in your code repo (Engineering)



```bash

# Go to your actual project

cd ~/code/my-project

claude



# Tell Claude to load the PRD:

"Read ~/prd/prj/my-project/user-login/task.md and sessions.md,

 then help me implement the requirements"



# Work with Claude to build the feature...



# When done, tell Claude to save the session:

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

```



### Common Commands



**Use `just` in ~/prd to manage tasks:**



```bash

cd ~/prd

just                    # Show all commands

just new PROJECT TASK   # Create a new task

just edit PROJECT TASK  # Edit requirements in text editor

just list              # List all tasks with status

just status            # Show overview stats

just work-on PROJECT TASK  # Show how to work on this task

just view PROJECT TASK  # View task.md quickly

just archive PROJECT TASK  # Archive completed task

```



**Use `claude` in your actual project directory only:**



```bash

cd ~/code/your-project

claude  # Work with Claude Code here, referencing ~/prd files

```



## Folder Structure



```

~/prd/

├── README.md              # This file (version controlled)

├── TEMPLATE.md            # Template for new task.md files (version controlled)

├── Justfile               # Automation commands (version controlled)

├── .gitignore             # Git ignore rules (version controlled)

└── prj/                   # Your projects directory (git-ignored!)

    └── {project}/         # One folder per project

        └── {task}/        # One folder per task

            ├── task.md        # Task requirements and details

            ├── sessions.md    # Work session log

            └── workflow.md    # Optional: Step-by-step workflow guide

```



**What gets version controlled:**

- ✅ System files: README.md, Justfile, TEMPLATE.md, .gitignore

- ✅ Example project: `prj/acme-app/` (for documentation)

- ❌ Your projects: Everything else in `prj/` stays local



**Example with your projects:**

```

~/prd/

├── README.md

├── TEMPLATE.md

├── Justfile

├── .gitignore

└── prj/

    ├── acme-app/               # ✅ Version controlled (example only)

    │   └── user-authentication/

    │       ├── task.md

    │       └── sessions.md

    ├── work-project/           # ❌ Git-ignored (your private work)

    │   ├── feature-x/

    │   └── feature-y/

    └── personal-site/          # ❌ Git-ignored (your personal stuff)

        └── blog-redesign/

```



> **Note:** The `prj/acme-app/` directory is included as a working example. Explore `prj/acme-app/user-authentication/` to see how tasks should be structured. Delete it anytime - it's just for learning!



## Creating a New Task



```bash

cd ~/prd

just new PROJECT-NAME TASK-NAME

```



This automatically:

- Creates the project directory if it doesn't exist

- Creates the task directory

- Copies the template to task.md

- Creates an empty sessions.md file

- Shows you the next steps



Then edit the task requirements in your text editor:

```bash

just edit PROJECT-NAME TASK-NAME

```



This opens task.md in your default editor (set via $EDITOR, or uses code/vim/nano). Fill in:

- Background (why this task exists)

- Requirements (what needs to be done)

- Goals (what success looks like)

- Success Criteria (how to know when it's complete)



**Pro tip:** For complex requirements, work with Claude Code in ~/prd:

```bash

cd ~/prd

claude

# "I have these requirements [paste]. Help me create a comprehensive

#  task.md file at prj/PROJECT/TASK/task.md"

```



## Daily Workflow



Remember: You'll be working in **two contexts** - planning in ~/prd and coding in your repos.



### 1. Check Your Tasks (Context: ~/prd)



```bash

cd ~/prd

just list    # See all your tasks

just status  # Quick overview

```



### 2. Review Task Details (Context: ~/prd)



```bash

cd ~/prd

just work-on PROJECT TASK   # Get instructions

just view PROJECT TASK      # View task.md

just sessions PROJECT TASK  # View session history

just workflow PROJECT TASK  # View workflow guide (if exists)

```



### 3. Refine/Plan if Needed (Context: ~/prd with Claude)



If you need to update requirements, create workflow guides, or plan approach:



```bash

cd ~/prd

claude

# "Read prj/PROJECT/TASK/task.md. I need to add requirements for X.

#  Also create a workflow.md with implementation phases."

```



### 4. Implement in Your Code Repo (Context: your code repo with Claude)



**Go to your actual project directory**:



```bash

cd ~/code/your-actual-project

claude

```



**Tell Claude Code to load the task:**

```

Read ~/prd/prj/PROJECT/TASK/task.md and ~/prd/prj/PROJECT/TASK/sessions.md



Give me a summary of:

1. What this task requires

2. What was accomplished in the last session

3. What needs to be done next



Then help me implement the requirements.

```



Claude Code will:

- Read your PRD files for context

- Understand the requirements

- See what's been done

- Help you implement the remaining work



### 5. Save Your Session (Context: back in code repo with Claude)



When you're done working, tell Claude Code to update your session log:



```

Update ~/prd/prj/PROJECT/TASK/sessions.md with a new session entry for today.



Include:

- Date: [today's date]

- Accomplished: [what we did]

- Blockers: [any issues]

- Decisions: [choices we made]

- Next steps: [what to do next]

- Status: In Progress

```



Claude will append the session entry to your sessions.md file.



### 6. Archive When Complete (Context: ~/prd)



```bash

cd ~/prd

just archive PROJECT TASK

```



### Example: Complete Workflow



Here's a complete example from start to finish:



```bash

# ============================================

# Part 1: Set up the task (in ~/prd)

# ============================================



cd ~/prd

just new acme-app user-authentication



# Edit requirements in your text editor

just edit acme-app user-authentication

# Fill in: Background, Requirements, Goals, Success Criteria

# Save and close



# Review what you created

just view acme-app user-authentication



# Get instructions for working on it

just work-on acme-app user-authentication



# ============================================

# Part 2: Implement the feature (in your project)

# ============================================



cd ~/code/acme-app

claude



# Tell Claude:

# "Read ~/prd/prj/acme-app/user-authentication/task.md and sessions.md

#

#  Summarize:

#  1. What this task requires

#  2. What was accomplished previously (if any)

#  3. What needs to be done

#

#  Then help me implement the authentication system."



# Work with Claude to implement, test, iterate...



# When done for the day, tell Claude:

# "Update ~/prd/prj/acme-app/user-authentication/sessions.md with a new session.

#

#  Accomplished:

#  - Set up JWT token generation

#  - Implemented login endpoint

#  - Added password hashing with bcrypt

#

#  Blockers: None

#

#  Decisions:

#  - Using HTTP-only cookies for tokens

#  - Session expiry set to 7 days

#

#  Next steps:

#  - Add password reset functionality

#  - Write tests for login endpoint

#

#  Status: In Progress"



# ============================================

# Part 3: Continue next session (next day)

# ============================================



cd ~/code/acme-app

claude



# Tell Claude:

# "Read ~/prd/prj/acme-app/user-authentication/task.md and sessions.md

#  Show me where we left off and help me continue."



# ============================================

# Part 4: Archive when complete (in ~/prd)

# ============================================



cd ~/prd

just archive acme-app user-authentication

```



## Writing Good task.md Files



### Be Specific

- Clearly define what "done" looks like

- Include concrete acceptance criteria

- List specific technical constraints



### Provide Context

- Explain WHY this task exists

- Link to related documents or resources

- Note dependencies on other tasks



### Define Scope

- Explicitly state what's IN scope

- Explicitly state what's OUT of scope (Non-Goals)

- This prevents scope creep



### Example Structure

```markdown

## Requirements

- MUST authenticate users via OAuth2

- MUST support GitHub and Google providers

- MUST redirect to dashboard after login



## Non-Goals

- Social login with Twitter (future task)

- Password-based authentication (deprecated)

```



## sessions.md Format



Each session entry follows this structure:



```markdown

## Session: 2025-01-15 - 2 hours



**Accomplished:**

- Implemented OAuth2 flow for GitHub

- Added redirect logic to dashboard

- Created login button component



**Blockers:**

- Google OAuth credentials not yet available in staging

- Need design review for button placement



**Decisions:**

- Using NextAuth.js instead of custom OAuth implementation

- Storing session in HTTP-only cookies (not localStorage)



**Next Steps:**

- Get Google OAuth credentials from DevOps

- Schedule design review meeting

- Add error handling for failed auth



**Status:** In Progress

```



### Guidelines for Sessions



1. **Update after each work session** (even short ones)

2. **Be honest about blockers** - they help you track patterns

3. **Document decisions** - you'll forget why you chose something

4. **Keep "Next Steps" actionable** - make it easy to resume

5. **Update status** - In Progress, Blocked, Complete, or On Hold



## Tips for Staying Organized



### 1. One Task, One Folder

Don't combine multiple unrelated tasks in one folder. If a task grows too large, split it.



### 2. Archive Completed Tasks

```bash

cd ~/prd

just archive PROJECT TASK

```



### 3. Use Descriptive Names

- Good: `user-authentication`, `api-rate-limiting`, `dark-mode-ui`

- Bad: `task1`, `fix-bug`, `new-feature`



### 4. Reference Tasks in Commits

Link commits to your PRD tasks:

```bash

git commit -m "Add OAuth flow (prd: acme-app/user-authentication)"

```



### 5. Review Weekly

Spend 15 minutes each week reviewing:

- What tasks are in progress?

- What tasks are blocked and why?

- What tasks can be archived?



### 6. Start Small

Don't create PRDs for every tiny task. Use this system for:

- Tasks taking more than 1 hour

- Tasks spanning multiple sessions

- Tasks requiring research or planning

- Tasks with multiple requirements



## Working with Project-Specific CLAUDE.md Files



Many projects have a `CLAUDE.md` file at the repository root with project-specific context. This PRD system complements those files:



- **CLAUDE.md**: Project-wide context, architecture, conventions

- **PRD task.md**: Specific feature/task requirements and goals



### Example Workflow



1. Project has `/code/acme-app/CLAUDE.md` with architecture details

2. You create `~/prd/acme-app/user-authentication/task.md` for a specific feature

3. When working, Claude reads both:

   ```

   "Read ~/code/acme-app/CLAUDE.md for project context,

    then read ~/prd/acme-app/user-authentication/task.md for this task's

    requirements, and help me implement the authentication system"

   ```



### Best Practice



Include a "Resources" section in your task.md that references the project's CLAUDE.md:

```markdown

## Resources

- Project context: ~/code/acme-app/CLAUDE.md

- API docs: https://docs.acme-app.dev

- Design mockups: Figma link

```



## Working with Multi-Repo Tasks



Some tasks require changes across multiple repositories (e.g., updating a backend API and its consumer service). You can track these in a single PRD task.



### Strategy for Multi-Repo Tasks



1. **One task, multiple repos** - Keep everything in one task.md and sessions.md

2. **Document the repos** - List all involved repositories in Technical Notes

3. **Note which repo** - When updating sessions.md, mention which repo you worked in

4. **Switch contexts** - Change directories and start Claude in each repo as needed



### Example Workflow



```bash

# Create a single task for the multi-repo work

cd ~/prd

just new backend-migration api-migration



# Edit task.md to document both repos

just edit backend-migration api-migration

# Add: Local project paths for both repos in Technical Notes

# Add: Multi-Repo Strategy section explaining which changes go where



# Work on first repo

cd ~/code/api-service

claude

# Tell Claude: "Read ~/prd/prj/backend-migration/api-migration/task.md and sessions.md

#               Work on the API changes. Note 'api-service repo' in session log."



# Work on second repo

cd ~/code/consumer-service

claude

# Tell Claude: "Read ~/prd/prj/backend-migration/api-migration/task.md and sessions.md

#               Work on the consumer changes. Note 'consumer-service repo' in session log."

```



### Using workflow.md for Complex Tasks



For complex tasks (especially multi-repo ones), create a `workflow.md` file in your task directory with detailed, step-by-step instructions:



**What to include:**

- Phase-by-phase breakdown of the entire task

- Exact bash commands to run (which directory, which repo)

- Complete Claude prompts to use at each step

- Expected outcomes for each phase

- Tips, gotchas, and lessons learned

- Quick reference (paths, contacts, key info)



**Why it's useful:**

- Provides a clear roadmap when you have a complex task

- Ensures you don't forget steps when switching between sessions

- Makes it easy to pick up where you left off

- Serves as documentation for similar tasks in the future



**Example structure:**

```markdown

# Task Name - Detailed Workflow



## Phase 1: Discovery

### Session 1a: Analyze Repo A

cd /path/to/repo-a

claude

# Tell Claude: "Read ~/prd/prj/PROJECT/TASK/task.md and sessions.md..."



### Session 1b: Analyze Repo B

cd /path/to/repo-b

claude

# Tell Claude: "Read ~/prd/prj/PROJECT/TASK/task.md and sessions.md..."

```



**View your workflow:**

```bash

just workflow PROJECT TASK

```



### Best Practices



- **Implementation order matters** - Document which repo to work on first (usually consumer before producer, or API before client)

- **Test integration** - Your Success Criteria should include integration testing across both repos

- **Track both repos** - Session entries should note which repo work was done in



Example session entry:

```markdown

## Session: 2025-01-15 - 3 hours



**Repo: api-service**



**Accomplished:**

- Created new /chargebacks endpoint

- Added validation logic

...

```



## Quick Reference



### Just Commands (run in ~/prd)



| Command | Purpose |

|---------|---------|

| `just` or `just --list` | Show all available commands |

| `just new PROJECT TASK` | Create new task with template |

| `just edit PROJECT TASK` | Edit task.md in text editor |

| `just view PROJECT TASK` | View task.md quickly |

| `just sessions PROJECT TASK` | View session history |

| `just workflow PROJECT TASK` | View workflow guide (if exists) |

| `just list` | List all projects and tasks with status |

| `just status` | Show overview stats |

| `just work-on PROJECT TASK` | Show instructions for working on task |

| `just path PROJECT TASK` | Get full path to task directory |

| `just search KEYWORD` | Search across all tasks |

| `just archive PROJECT TASK` | Archive completed task |

| `just tree` | Show file tree structure |



### Working with Claude Code (run in your project)



```bash

# From your actual project directory (NOT ~/prd):

cd ~/code/your-project

claude



# Tell Claude to load your PRD task:

"Read ~/prd/prj/PROJECT/TASK/task.md and sessions.md, then help me implement it"



# Tell Claude to save your session:

"Update ~/prd/prj/PROJECT/TASK/sessions.md with today's session"

```



## 🔄 Staying Up to Date



This system is actively maintained with new features and improvements. Here's how to stay current:



### Getting Updates



```bash

cd ~/prd



# Pull latest improvements from upstream

git fetch upstream

git merge upstream/main



# If you haven't set up upstream yet, see Installation section above

```



**What gets updated when you pull:**

- ✅ New automation commands in Justfile

- ✅ Documentation improvements in README

- ✅ Enhanced templates in TEMPLATE.md

- ✅ Updates to the example project (acme-app)



**What stays completely untouched:**

- ✅ Your projects (everything in `prj/` except acme-app)

- ✅ Your work-in-progress tasks

- ✅ Your session histories and notes



### Verifying Your Setup



To ensure your projects are private and protected:



```bash

cd ~/prd



# Check what git is tracking

git ls-files prj/

# Should ONLY show: prj/acme-app/* files



# Create a test project

just new test-project test-task



# Verify it's not tracked

git status

# Should show: "nothing to commit, working tree clean"

# (your test project won't appear in untracked files)



# Clean up

rm -rf prj/test-project

```



### Optional: Version Control Your Own Projects



If you want to track your own projects separately:



```bash

# Option 1: Separate repo for projects

cd ~/prd/prj

git init

git add .

git commit -m "My personal PRD projects"



# Option 2: Modify .gitignore to track specific projects

# Edit .gitignore and add:

# !prj/my-important-project

# !prj/my-important-project/**

```



## Customization & Tips



This system is designed to be simple and flexible. Adapt it to your needs:

- **Add custom fields** to task.md (e.g., Priority, Estimated Time)

- **Change the session format** to match your workflow

- **Create project-specific templates** for common task types

- **Extend the Justfile** with your own automation recipes

- **Add git tracking** to your PRD directory to version control your tasks



### Example: Adding a Custom Justfile Recipe



Edit `~/prd/Justfile` and add:

```justfile

# List only blocked tasks

blocked:

    @grep -r "Status.*Blocked" --include="sessions.md" . || echo "No blocked tasks"

```



### Example: Tracking the PRD System



The system files are already tracked if you forked/cloned the repo. To track your own projects:



```bash

# Track a specific project (modify .gitignore first)

# Add to .gitignore:

# !prj/my-important-project

# !prj/my-important-project/**



git add prj/my-important-project

git commit -m "Add my important project"

```



The goal is to make it easier to manage complex tasks across multiple projects without losing context or progress.