claude-code-waypoint

内容来源：README.md（说明文档） · 原始地址 · 查看安装指南

原始内容

# Claude Code Waypoint

[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
[![Version](https://img.shields.io/badge/version-2.0.0-blue)](CHANGELOG.md)

**Never lose context again.** Strategic waypoints for persistent memory and intentional context management in Claude Code projects.

---

## The Problem

Working with AI on complex projects means:
- ❌ **Context resets** force you to start from scratch
- ❌ **Lost decisions** - no record of why choices were made
- ❌ **Forgotten progress** - can't remember what's done
- ❌ **Broken continuity** - every session feels like day one
- ❌ **Manual repetition** - explaining the same things over and over

## The Solution

Claude Code Waypoint creates **strategic checkpoints** throughout your project journey:

- ✅ **Resume in < 60 seconds** after any context reset
- ✅ **Persistent memory** across sessions, days, weeks
- ✅ **Auto-activating skills** provide the right context automatically
- ✅ **Decision logging** captures the "why" behind choices
- ✅ **Works beyond code** - planning, research, any long-running work

**Waypoints are navigation markers** that help you track progress, return to known points, and resume quickly from exactly where you left off.

---

## 🚀 Quick Start

### Installation

Copy Claude Code Waypoint to your project:

```bash
# Clone this repository
git clone https://github.com/DojoCodingLabs/claude-code-waypoint

# Copy to your project
cp -r claude-code-waypoint/.claude /path/to/your/project/
cp -r claude-code-waypoint/plans /path/to/your/project/

# Set up hooks
cd /path/to/your/project/.claude/hooks
npm install && chmod +x *.sh
```

### Your First Waypoint

```bash
# Create a waypoint for a feature
/create-plan auth-implementation

# Work on your feature...
# Waypoint tracks context automatically

# Before taking a break
/update-context

# Resume later (even after context reset)
/resume auth-implementation
# → Back to work in < 60 seconds
```

**[→ Detailed Installation Guide](https://github.com/dojocodinglabs/claude-code-waypoint/blob/HEAD/INSTALLATION.md)**

---

## 📖 How to Use: The Waypoint Workflow

### Step 1: Plan First (Think & Document)

Start by having Claude help you think through requirements:

```bash
/plan Build authentication system with OAuth and JWT
```

Claude will help you:
- Clarify requirements and edge cases
- Identify technical decisions
- Consider architecture options
- Document initial approach

**Key Point:** This is exploration mode. Ask questions, refine thinking, iterate.

### Step 2: Create Official Waypoint (Formalize)

Once requirements are clear, formalize into waypoint structure:

```bash
/create-plan auth-system
```

This creates the **3-file waypoint**:
```
plans/active/auth-system/
├── auth-system-plan.md      # Strategy & architecture
├── auth-system-context.md   # Current state & decisions
└── auth-system-tasks.md     # Actionable checklist
```

Claude will populate these based on your planning discussion.

### Step 3: Review & Approve (Your Responsibility)

**This is critical:** You are the builder, you own the plan.

```bash
# Review the waypoint files
cat plans/active/auth-system/auth-system-plan.md

# Check if approach makes sense
# Verify architecture decisions align with your goals
# Ensure nothing critical is missing
```

**Ask yourself:**
- Does this approach make sense for my project?
- Are the trade-offs acceptable?
- What could go wrong?

**Approve explicitly:**
```
"I've reviewed the auth-system plan and approve it. Let's proceed."
```

### Step 4: Execute (Stay Context-Aware)

Now implement with Claude, maintaining context throughout:

```bash
# Claude implements based on approved plan
# Waypoint tracks progress automatically

# Before long breaks or context reset risk
/update-context

# After context reset
/resume auth-system
# → Back in < 60 seconds with full context
```

**While executing:**
- Update waypoint when you discover new information
- Log decisions and why they were made
- Track what's completed vs pending
- Document blockers as they appear

---

## 🎯 Core Features

### 1. Persistent Memory System (PRIMARY)

The **3-file waypoint structure** captures everything:

```
plans/active/auth-implementation/
├── auth-implementation-plan.md      # Strategy (rarely changes)
├── auth-implementation-context.md   # Current state (updated frequently)
└── auth-implementation-tasks.md     # Actionable checklist (daily updates)
```

**What gets tracked:**
- **Decisions** - Why you chose specific approaches
- **Progress** - What's done, in progress, and pending
- **Blockers** - What's preventing progress
- **Next actions** - Specific file + function to work on
- **Key discoveries** - Important findings during work

**SESSION PROGRESS tracking** enables the < 60 second resume:

```markdown
## SESSION PROGRESS (2025-01-15 14:30)

### ✅ COMPLETED
- [x] Task 1 done
- [x] Task 2 done

### 🟡 IN PROGRESS
- [ ] Task 3 (CURRENT)

### 🎯 NEXT ACTION
Edit src/auth/login.ts - implement validateCredentials()
```

**[→ Deep dive: Waypoint Pattern](https://github.com/dojocodinglabs/claude-code-waypoint/blob/HEAD/WAYPOINT_PATTERN.md)**

### 2. Auto-Activation System (CRITICAL)

Skills auto-activate based on context - right knowledge at the right time:

```
User types: "Create a new plan for..."
    ↓
Hook analyzes: prompt keywords + active files
    ↓
Auto-suggests: context-persistence skill
    ↓
Claude gets: Perfect context automatically
```

**Key skills that auto-activate:**
- **memory-management** - When you need to remember preferences
- **context-persistence** - When working with waypoint files
- **plan-approval** - When making significant changes

**[→ Learn more: Auto-Activation System](https://github.com/dojocodinglabs/claude-code-waypoint/blob/HEAD/.claude/hooks/AUTO_ACTIVATION.md)**

### 3. Commands for Waypoint Management

- `/create-plan [task]` - Create new waypoint (3-file structure)
- `/update-context` - Update waypoint before context reset
- `/resume [task]` - Resume from existing waypoint

### 4. Specialized Agents

Copy-and-use agents for common workflows:
- **scaffold-customizer** - Adapt skills to your tech stack
- **documentation-architect** - Generate comprehensive docs
- **code-architecture-reviewer** - Review code for consistency
- **refactor-planner** - Plan refactoring strategies
- **plan-reviewer** - Review development plans
- **web-research-specialist** - Research technical issues

**[→ View all agents](https://github.com/dojocodinglabs/claude-code-waypoint/tree/HEAD/.claude/agents/)**

---

## 📚 What's Included

### Core Skills (Memory & Context)

| Skill | Purpose |
|-------|---------|
| **memory-management** | Intentional memory tracking and preference learning |
| **context-persistence** | Waypoint pattern implementation |
| **plan-approval** | User control workflows for complex changes |

These work with **any tech stack** - they're methodology, not code.

### Example Scaffolds (Opinionated)

| Skill | Tech Stack |
|-------|------------|
| **frontend-dev-guidelines** | Next.js 14+ + React 19 + shadcn/ui |
| **backend-dev-guidelines** | Supabase + Edge Functions |

**Not using our stack?** Use the `scaffold-customizer` agent to adapt skills for your tech.

**[→ Customization guide](https://github.com/dojocodinglabs/claude-code-waypoint/blob/HEAD/CUSTOMIZATION.md)**

### Skill Developer (Meta)

The **skill-developer** skill teaches you how to create custom skills with memory patterns.

**[→ Learn skill development](https://github.com/dojocodinglabs/claude-code-waypoint/tree/HEAD/.claude/skills/skill-developer/)**

---

## 💡 Use Cases

### 🖥️ Software Development

```
Feature: Authentication refactor
Waypoint tracks:
- Current architecture decisions
- Migration progress (which files done)
- Blockers and workarounds discovered
- Testing approach and edge cases
- Performance benchmarks

Resume time: 45 seconds
```

### 📊 Business Planning

```
Project: Q1 strategy redesign
Waypoint tracks:
- Market research findings
- Stakeholder feedback
- Strategic options considered
- Resource allocation decisions
- Implementation timeline

Resume time: 30 seconds
```

### 🔬 Research Projects

```
Research: ML model optimization
Waypoint tracks:
- Experiment results
- Hyperparameter tuning notes
- Performance comparisons
- Dead ends and why they failed
- Next experiment hypotheses

Resume time: 60 seconds
```

**The waypoint pattern works for any long-running work that requires persistent context.**

---

## 🌟 Credits & Origin

This project packages the incredible work shared by **[diet103](https://github.com/diet103)** in their repository **[claude-code-infrastructure-showcase](https://github.com/diet103/claude-code-infrastructure-showcase)**.

### Original Inspiration

From the Reddit post: **["Claude Code is a Beast - Tips from 6 Months of Hardcore Use"](https://www.reddit.com/r/ClaudeAI/comments/1h4riv1/claude_code_is_a_beast_tips_from_6_months_of/)**

### What We Did

Building on this foundation, we added our own twist and improvements:
- **Introduced the "Waypoint" metaphor** - Renamed "dev docs" to "waypoints"
- **Transformed into distributable package** - Proper repository structure
- **Enhanced documentation** - Created comprehensive guides
- **Improved organization** - Restructured as `plans/` directory
- **Positioned correctly** - Memory/context management as PRIMARY
- **Made it accessible** - Simple copy-paste installation

**Core credit** goes to **diet103** for the innovative infrastructure patterns and 6 months of real-world validation.

---

## 📖 Documentation

### Getting Started
- **[Installation Guide](https://github.com/dojocodinglabs/claude-code-waypoint/blob/HEAD/INSTALLATION.md)** - Detailed setup instructions
- **[Waypoint Pattern](https://github.com/dojocodinglabs/claude-code-waypoint/blob/HEAD/WAYPOINT_PATTERN.md)** - Deep dive into the 3-file structure
- **[Philosophy](https://github.com/dojocodinglabs/claude-code-waypoint/blob/HEAD/PHILOSOPHY.md)** - Why intentional memory matters

### Advanced Usage
- **[Customization Guide](https://github.com/dojocodinglabs/claude-code-waypoint/blob/HEAD/CUSTOMIZATION.md)** - Adapt to your tech stack
- **[Integration Guide](https://github.com/dojocodinglabs/claude-code-waypoint/blob/HEAD/WAYPOINT_INTEGRATION_GUIDE.md)** - AI-assisted setup
- **[Contributing](https://github.com/dojocodinglabs/claude-code-waypoint/blob/HEAD/CONTRIBUTING.md)** - How to contribute

### Technical Reference
- **[CLAUDE.md](https://github.com/dojocodinglabs/claude-code-waypoint/blob/HEAD/CLAUDE.md)** - Architecture for Claude Code
- **[Auto-Activation System](https://github.com/dojocodinglabs/claude-code-waypoint/blob/HEAD/.claude/hooks/AUTO_ACTIVATION.md)** - How hooks work
- **[Skills Directory](https://github.com/dojocodinglabs/claude-code-waypoint/tree/HEAD/.claude/skills/)** - All available skills

---

## 🤝 Contributing

We welcome contributions! See [CONTRIBUTING.md](https://github.com/dojocodinglabs/claude-code-waypoint/blob/HEAD/CONTRIBUTING.md) for guidelines.

**Contributions welcome:**
- Bug fixes and improvements
- New skills for different tech stacks
- Documentation enhancements
- Example waypoint templates

---

## 📄 License

MIT License - See [LICENSE](https://github.com/dojocodinglabs/claude-code-waypoint/tree/HEAD/LICENSE) for details.

---

## 💬 Support

- **Issues:** [GitHub Issues](https://github.com/DojoCodingLabs/claude-code-waypoint/issues)
- **Discussions:** [GitHub Discussions](https://github.com/DojoCodingLabs/claude-code-waypoint/discussions)

---

<p align="center">
  <strong>Built by Dojo Coding, for Builders.</strong><br>
  Production-tested tools for serious Claude Code users.
</p>

Claude Code Waypoint

Never lose context again. Strategic waypoints for persistent memory and intentional context management in Claude Code projects.

The Problem

Working with AI on complex projects means:

❌ Context resets force you to start from scratch
❌ Lost decisions - no record of why choices were made
❌ Forgotten progress - can't remember what's done
❌ Broken continuity - every session feels like day one
❌ Manual repetition - explaining the same things over and over

The Solution

Claude Code Waypoint creates strategic checkpoints throughout your project journey:

✅ Resume in < 60 seconds after any context reset
✅ Persistent memory across sessions, days, weeks
✅ Auto-activating skills provide the right context automatically
✅ Decision logging captures the "why" behind choices
✅ Works beyond code - planning, research, any long-running work

Waypoints are navigation markers that help you track progress, return to known points, and resume quickly from exactly where you left off.

🚀 Quick Start

Installation

Copy Claude Code Waypoint to your project:

# Clone this repository
git clone https://github.com/DojoCodingLabs/claude-code-waypoint

# Copy to your project
cp -r claude-code-waypoint/.claude /path/to/your/project/
cp -r claude-code-waypoint/plans /path/to/your/project/

# Set up hooks
cd /path/to/your/project/.claude/hooks
npm install && chmod +x *.sh

Your First Waypoint

# Create a waypoint for a feature
/create-plan auth-implementation

# Work on your feature...
# Waypoint tracks context automatically

# Before taking a break
/update-context

# Resume later (even after context reset)
/resume auth-implementation
# → Back to work in < 60 seconds

→ Detailed Installation Guide

📖 How to Use: The Waypoint Workflow

Step 1: Plan First (Think & Document)

Start by having Claude help you think through requirements:

/plan Build authentication system with OAuth and JWT

Claude will help you:

Clarify requirements and edge cases
Identify technical decisions
Consider architecture options
Document initial approach

Key Point: This is exploration mode. Ask questions, refine thinking, iterate.

Step 2: Create Official Waypoint (Formalize)

Once requirements are clear, formalize into waypoint structure:

/create-plan auth-system

This creates the 3-file waypoint:

plans/active/auth-system/
├── auth-system-plan.md      # Strategy & architecture
├── auth-system-context.md   # Current state & decisions
└── auth-system-tasks.md     # Actionable checklist

Claude will populate these based on your planning discussion.

Step 3: Review & Approve (Your Responsibility)

This is critical: You are the builder, you own the plan.

# Review the waypoint files
cat plans/active/auth-system/auth-system-plan.md

# Check if approach makes sense
# Verify architecture decisions align with your goals
# Ensure nothing critical is missing

Ask yourself:

Does this approach make sense for my project?
Are the trade-offs acceptable?
What could go wrong?

Approve explicitly:

"I've reviewed the auth-system plan and approve it. Let's proceed."

Step 4: Execute (Stay Context-Aware)

Now implement with Claude, maintaining context throughout:

# Claude implements based on approved plan
# Waypoint tracks progress automatically

# Before long breaks or context reset risk
/update-context

# After context reset
/resume auth-system
# → Back in < 60 seconds with full context

While executing:

Update waypoint when you discover new information
Log decisions and why they were made
Track what's completed vs pending
Document blockers as they appear

🎯 Core Features

1. Persistent Memory System (PRIMARY)

The 3-file waypoint structure captures everything:

plans/active/auth-implementation/
├── auth-implementation-plan.md      # Strategy (rarely changes)
├── auth-implementation-context.md   # Current state (updated frequently)
└── auth-implementation-tasks.md     # Actionable checklist (daily updates)

What gets tracked:

Decisions - Why you chose specific approaches
Progress - What's done, in progress, and pending
Blockers - What's preventing progress
Next actions - Specific file + function to work on
Key discoveries - Important findings during work

SESSION PROGRESS tracking enables the < 60 second resume:

## SESSION PROGRESS (2025-01-15 14:30)

### ✅ COMPLETED
- [x] Task 1 done
- [x] Task 2 done

### 🟡 IN PROGRESS
- [ ] Task 3 (CURRENT)

### 🎯 NEXT ACTION
Edit src/auth/login.ts - implement validateCredentials()

→ Deep dive: Waypoint Pattern

2. Auto-Activation System (CRITICAL)

Skills auto-activate based on context - right knowledge at the right time:

User types: "Create a new plan for..."
    ↓
Hook analyzes: prompt keywords + active files
    ↓
Auto-suggests: context-persistence skill
    ↓
Claude gets: Perfect context automatically

Key skills that auto-activate:

memory-management - When you need to remember preferences
context-persistence - When working with waypoint files
plan-approval - When making significant changes

→ Learn more: Auto-Activation System

3. Commands for Waypoint Management

/create-plan [task] - Create new waypoint (3-file structure)
/update-context - Update waypoint before context reset
/resume [task] - Resume from existing waypoint

4. Specialized Agents

Copy-and-use agents for common workflows:

scaffold-customizer - Adapt skills to your tech stack
documentation-architect - Generate comprehensive docs
code-architecture-reviewer - Review code for consistency
refactor-planner - Plan refactoring strategies
plan-reviewer - Review development plans
web-research-specialist - Research technical issues

→ View all agents

📚 What's Included

Core Skills (Memory & Context)

Skill	Purpose
memory-management	Intentional memory tracking and preference learning
context-persistence	Waypoint pattern implementation
plan-approval	User control workflows for complex changes

These work with any tech stack - they're methodology, not code.

Example Scaffolds (Opinionated)

Skill	Tech Stack
frontend-dev-guidelines	Next.js 14+ + React 19 + shadcn/ui
backend-dev-guidelines	Supabase + Edge Functions

Not using our stack? Use the scaffold-customizer agent to adapt skills for your tech.

→ Customization guide

Skill Developer (Meta)

The skill-developer skill teaches you how to create custom skills with memory patterns.

→ Learn skill development

💡 Use Cases

🖥️ Software Development

Feature: Authentication refactor
Waypoint tracks:
- Current architecture decisions
- Migration progress (which files done)
- Blockers and workarounds discovered
- Testing approach and edge cases
- Performance benchmarks

Resume time: 45 seconds

📊 Business Planning

Project: Q1 strategy redesign
Waypoint tracks:
- Market research findings
- Stakeholder feedback
- Strategic options considered
- Resource allocation decisions
- Implementation timeline

Resume time: 30 seconds

🔬 Research Projects

Research: ML model optimization
Waypoint tracks:
- Experiment results
- Hyperparameter tuning notes
- Performance comparisons
- Dead ends and why they failed
- Next experiment hypotheses

Resume time: 60 seconds

The waypoint pattern works for any long-running work that requires persistent context.

🌟 Credits & Origin

This project packages the incredible work shared by diet103 in their repository claude-code-infrastructure-showcase.

Original Inspiration

From the Reddit post: "Claude Code is a Beast - Tips from 6 Months of Hardcore Use"

What We Did

Building on this foundation, we added our own twist and improvements:

Introduced the "Waypoint" metaphor - Renamed "dev docs" to "waypoints"
Transformed into distributable package - Proper repository structure
Enhanced documentation - Created comprehensive guides
Improved organization - Restructured as plans/ directory
Positioned correctly - Memory/context management as PRIMARY
Made it accessible - Simple copy-paste installation

Core credit goes to diet103 for the innovative infrastructure patterns and 6 months of real-world validation.

📖 Documentation

Getting Started

Installation Guide - Detailed setup instructions
Waypoint Pattern - Deep dive into the 3-file structure
Philosophy - Why intentional memory matters

Advanced Usage

Customization Guide - Adapt to your tech stack
Integration Guide - AI-assisted setup
Contributing - How to contribute

Technical Reference

CLAUDE.md - Architecture for Claude Code
Auto-Activation System - How hooks work
Skills Directory - All available skills

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Contributions welcome:

Bug fixes and improvements
New skills for different tech stacks
Documentation enhancements
Example waypoint templates

📄 License

MIT License - See LICENSE for details.

💬 Support

Issues: GitHub Issues
Discussions: GitHub Discussions

Built by Dojo Coding, for Builders.
Production-tested tools for serious Claude Code users.