- Introduction
- Project Setup and Structure
- Effective Communication Patterns
- Session Management
- Strategic Checkpoints
- Context Persistence
- Troubleshooting
- Testing and Quality Assurance
- Templates Library
- Example Workflow
Working with AI development tools like Claude Code presents unique challenges and opportunities. Unlike human developers, AI tools may not naturally recognize when to pause for feedback and can lose context between sessions. This manual provides a structured approach to maximize the effectiveness of your AI development partnership.
The primary challenges addressed in this guide include:
-
Continuous Flow: AI can get into a "flow state" and continue generating code without natural stopping points. Unlike human developers who recognize when to pause for feedback, AI tools need explicit guidance on when to stop for review.
-
Context Loss: Sessions get interrupted, chats close accidentally, or context windows fill up, resulting in the AI losing track of what has been built so far. This creates discontinuity in the development process.
This manual offers practical strategies to establish a collaborative rhythm with AI developer tools without disrupting their productive flow, while maintaining context across sessions.
When starting a new project with an AI counterpart, begin with:
I'm starting a new project called [PROJECT_NAME]. It's [BRIEF_DESCRIPTION].
Here's our project manifest to track progress:
[PASTE STANDARD PROJECT MANIFEST]
Let's begin by [SPECIFIC FIRST TASK]. Please acknowledge this context before we start.
When resuming work after a break or context loss:
We're continuing work on [PROJECT_NAME]. Here's our current project manifest:
[PASTE FILLED-IN PROJECT MANIFEST]
Here's a quick summary of where we left off:
[PASTE FILLED-IN QUICK SESSION RESUME]
Please review this information and let me know if you have any questions before we continue.
Project manifests serve as a central reference point for maintaining context across development sessions. Two types of manifests are provided based on project complexity:
- Standard Project Manifest: For comprehensive projects with multiple components
- Minimal Project Manifest: For smaller projects or focused development sessions
Use these manifests to:
- Record architectural decisions
- Track progress on different components
- Document current status and next steps
- Maintain important context across sessions
Begin each session with clear objectives:
Today, we're focusing on [SPECIFIC_GOAL]. Our success criteria are:
1. [CRITERION_1]
2. [CRITERION_2]
3. [CRITERION_3]
Let's tackle this step by step.
Use a consistent command pattern to signal your intentions:
[ANALYZE]: Request analysis of code or a problem[IMPLEMENT]: Request implementation of a feature[REVIEW]: Request code review[DEBUG]: Request help with debugging[REFACTOR]: Request code improvement[DOCUMENT]: Request documentation[CONTINUE]: Signal to continue previous work
Example:
[IMPLEMENT] Create a user authentication system with the following requirements:
- Email/password login
- Social login (Google, Facebook)
- Multi-factor authentication
- Password reset flow
For complex features, provide specifications in a structured format:
We need to implement [FEATURE]. Here are the specifications:
Requirements:
- [REQUIREMENT_1]
- [REQUIREMENT_2]
- [REQUIREMENT_3]
Technical constraints:
- [CONSTRAINT_1]
- [CONSTRAINT_2]
Acceptance criteria:
- [CRITERION_1]
- [CRITERION_2]
- [CRITERION_3]
Please confirm your understanding of these requirements before proceeding.
Let's begin today's development session. Here's our agenda:
1. Review what we accomplished last time ([BRIEF_SUMMARY])
2. Continue implementing [CURRENT_FEATURE]
3. Test [COMPONENT(S)_TO_TEST]
We'll work on each item in sequence, pausing between them for my review.
Let's wrap up this session. Please provide a session summary using this template:
[PASTE SESSION SUMMARY TEMPLATE]
We'll use this to continue our work in the next session.
When you need to switch to a different component or feature:
We need to switch focus to [NEW_COMPONENT/FEATURE]. Here's the relevant context:
Component: [COMPONENT_NAME]
Status: [CURRENT_STATUS]
Files involved:
- [FILE_PATH_1]: [BRIEF_DESCRIPTION]
- [FILE_PATH_2]: [BRIEF_DESCRIPTION]
Let's put our current work on [CURRENT_COMPONENT] on hold and address this new priority.
Establish checkpoints to ensure collaborative development without disrupting productive flow.
Start your development session with clear checkpoint expectations:
"As you develop this feature, please pause at logical completion points and explicitly ask me if I want to test what you've built so far before continuing."
For more complex projects, establish a step-by-step process:
"Please develop this feature in stages:
1. First, design the component and wait for my approval
2. Implement the core functionality and pause for testing
3. Only after my feedback, continue to the next phase"
Establish checkpoints after:
- Architecture design – Before any code is written
- Core functionality – When basic features are implemented
- Database interactions – After schema design or query implementation
- API endpoints – When endpoints are defined but before full integration
- UI components – After key interface elements are created
- Integration points – When connecting different system components
Teach your AI to use these signaling phrases:
- CHECKPOINT: "I've completed [specific component]. Would you like to test this before I continue?"
- TESTING OPPORTUNITY: "This is a good moment to verify the implementation."
- MILESTONE REACHED: "[Feature X] is ready for user testing. Here's how to test it: [instructions]"
-
Be specific about testing requirements – "When you reach a testable point for the user authentication system, include instructions for testing both successful and failed login attempts."
-
Set time or complexity boundaries – "If you've been developing for more than 10 minutes without a checkpoint, please pause and check in."
-
Provide feedback on checkpoint frequency – "You're stopping too often/not often enough. Let's adjust to pause only after completing [specific scope]."
AI development tools have limited context windows and don't maintain state between sessions. When a chat closes or context is lost, the AI loses track of:
- Project structure and files
- Design decisions made
- Implementation details
- Current development stage
Implement a simple context management system with these components:
Create a project-manifest.md file that contains:
# Project Manifest: [Project Name]
## Project Overview
[Brief description of the project]
## Architecture
[Key architectural decisions]
## Current Status
- Last updated: [Date/Time]
- Current milestone: [e.g., "Implementing user authentication"]
- Current stage: [e.g., "70% complete"]
## Components
- [Component 1]: [Status] - [Brief description]
- [Component 2]: [Status] - [Brief description]
...
## Next Steps
- [Immediate next tasks]
- [Planned features]
## Testing Notes
- [Testing instructions]
- [Known issues]
## Configuration
- [Environment setup]
- [Dependencies]At each checkpoint:
- Save a snapshot of the current project state
- Update the manifest file with current status
- Export any critical implementation details
When restarting development:
- Share the project manifest with the AI
- Provide the most recent relevant code files
- Use this prompt template:
"We're continuing development on [Project Name]. Here's our project manifest and current status.
The last thing we implemented was [specific feature/component].
Please review the manifest and current code to understand where we left off.
Our next task is to [specific next task].
Please acknowledge your understanding of the current state before proceeding."
Use specially formatted comments that help with context resumption:
// [CONTEXT:START] Authentication System
// Implements JWT-based authentication with refresh tokens
// Current status: Login and registration complete, password reset in progress
// [CONTEXT:END]If the AI seems to be missing important context:
I notice you may be missing some key context. Here's what you need to know:
- [CRITICAL_PIECE_OF_CONTEXT_1]
- [CRITICAL_PIECE_OF_CONTEXT_2]
- [CRITICAL_PIECE_OF_CONTEXT_3]
Let's refocus on [CURRENT_TASK] with this information in mind.
If development is going in the wrong direction:
I'd like to redirect our approach. The current implementation [ISSUE_WITH_CURRENT_APPROACH].
Let's adjust by:
1. [ADJUSTMENT_1]
2. [ADJUSTMENT_2]
3. [ADJUSTMENT_3]
Does this new direction make sense to you?
If the AI continues without pausing at appropriate checkpoints:
- Intervene with: "Let's pause here. I'd like to test what we have so far."
- Reinforce the checkpoint pattern: "Going forward, please pause after completing each [component type]."
- Be specific about what you're testing and why to help the AI learn appropriate stopping points.
Now that we've implemented [FEATURE], please provide me with testing instructions:
1. How should I test the happy path?
2. What edge cases should I verify?
3. Are there any potential performance concerns I should look for?
4. How will I know if the implementation is successful?
I've tested [FEATURE] and here are my findings:
✅ Successes:
- [SUCCESS_1]
- [SUCCESS_2]
❌ Issues:
- [ISSUE_1]
- [ISSUE_2]
Let's address these issues before moving on.
# Project Manifest: [PROJECT_NAME]
## Project Overview
[PROJECT_DESCRIPTION]
## Current Status
- **Last Updated**: [DATE]
- **Current Phase**: [PHASE]
- **Progress**: [PROGRESS_PERCENTAGE]%
- **Active Branch**: [BRANCH_NAME]
## Key Architecture
- **Frontend**: [FRONTEND_TECH]
- **Backend**: [BACKEND_TECH]
- **Database**: [DATABASE_TECH]
- **Deployment**: [DEPLOYMENT_STRATEGY]
## Components/Modules
### 1. [COMPONENT_1_NAME]
- **Status**: [STATUS] ([PERCENTAGE]% complete)
- **Description**: [DESCRIPTION]
- **Current Task**: [CURRENT_TASK]
- **Next Task**: [NEXT_TASK]
- **Dependencies**: [DEPENDENCIES]
- **Testing**: [TESTING_APPROACH]
- **Location**: [CODE_LOCATION]
### 2. [COMPONENT_2_NAME]
- **Status**: [STATUS] ([PERCENTAGE]% complete)
- **Description**: [DESCRIPTION]
- **Current Task**: [CURRENT_TASK]
- **Next Task**: [NEXT_TASK]
- **Dependencies**: [DEPENDENCIES]
- **Testing**: [TESTING_APPROACH]
- **Location**: [CODE_LOCATION]
### 3. [COMPONENT_3_NAME]
- **Status**: [STATUS] ([PERCENTAGE]% complete)
- **Description**: [DESCRIPTION]
- **Current Task**: [CURRENT_TASK]
- **Next Task**: [NEXT_TASK]
- **Dependencies**: [DEPENDENCIES]
- **Testing**: [TESTING_APPROACH]
- **Location**: [CODE_LOCATION]
## Immediate Next Steps
1. [NEXT_STEP_1]
2. [NEXT_STEP_2]
3. [NEXT_STEP_3]
## Recent Decisions
- [DECISION_1] ([DATE])
- [DECISION_2] ([DATE])
- [DECISION_3] ([DATE])
## Known Issues
- [ISSUE_1]
- [ISSUE_2]
- [ISSUE_3]
## Environment Setup
- [REQUIREMENT_1]
- [REQUIREMENT_2]
- [REQUIREMENT_3]
- [CONFIGURATION_NOTES]
---
## Context Restoration Notes
Last session ([DATE]), we [PREVIOUS_WORK]. We left off at [STOPPING_POINT].
The next task is to [NEXT_TASK_DETAILS].
Key context for the current task:
- [CONTEXT_1]
- [CONTEXT_2]
- [CONTEXT_3]# Project Manifest: [PROJECT_NAME]
## Project Overview
[PROJECT_DESCRIPTION]
## Current Status
- **Last Updated**: [DATE]
- **Current Task**: [CURRENT_TASK]
- **Next Task**: [NEXT_TASK]
## Project Structure
- [KEY_COMPONENT_1]: [BRIEF_DESCRIPTION]
- [KEY_COMPONENT_2]: [BRIEF_DESCRIPTION]
- [KEY_COMPONENT_3]: [BRIEF_DESCRIPTION]
## Environment Setup
- [KEY_TECHNOLOGY_1]
- [KEY_TECHNOLOGY_2]
- [KEY_TECHNOLOGY_3]
## Context Restoration
Last session, we [PREVIOUS_WORK]. We're now working on [CURRENT_FOCUS].
Key context:
- [CRITICAL_CONTEXT_1]
- [CRITICAL_CONTEXT_2]# Quick Session Resume
## Project: [PROJECT_NAME]
I'm continuing our work on [PROJECT_NAME]. We're in the middle of implementing [FEATURE/COMPONENT].
## Current State
- We've completed: [COMPLETED_ITEMS]
- We're currently working on: [CURRENT_TASK]
- Our most recent change was: [LAST_CHANGE]
## Important Context
- [KEY_FILE_1] contains [RELEVANT_FUNCTIONALITY_1]
- [KEY_FILE_2] depends on [DEPENDENCY_INFORMATION]
- We decided to [RECENT_DECISION] because [REASONING]
## Today's Goal
Let's continue by [SPECIFIC_NEXT_TASK]. This involves:
1. [SUBTASK_1]
2. [SUBTASK_2]
3. [SUBTASK_3]
Please review this context and let me know when you're ready to continue.# Session Summary: [DATE]
## Project: [PROJECT_NAME]
## What Was Accomplished
- [ACCOMPLISHMENT_1]
- [ACCOMPLISHMENT_2]
- [ACCOMPLISHMENT_3]
## Code Changes
- [FILE_PATH_1]: [WHAT_CHANGED]
- [FILE_PATH_2]: [WHAT_CHANGED]
- [FILE_PATH_3]: [WHAT_CHANGED]
## Decisions Made
- [DECISION_1]
- [DECISION_2]
## Issues Encountered
- [ISSUE_1]: [BRIEF_DESCRIPTION]
- [ISSUE_2]: [BRIEF_DESCRIPTION]
## Next Steps
- [NEXT_STEP_1]
- [NEXT_STEP_2]
- [NEXT_STEP_3]
## Notes for Next Session
[IMPORTANT_CONTEXT_FOR_NEXT_SESSION]// [CONTEXT:START] [COMPONENT_NAME]
// Purpose: [COMPONENT_PURPOSE]
// Current status: [COMPONENT_STATUS]
// Key dependencies:
// - [DEPENDENCY_1]
// - [DEPENDENCY_2]
// Last modified: [DATE] - [CHANGES_MADE]
// Next planned changes: [PLANNED_CHANGES]
// Known issues:
// - [ISSUE_1]
// - [ISSUE_2]
// [CONTEXT:END]
// Regular code begins below this lineHere's a typical workflow using the templates and strategies in this manual:
-
Start project
- Create Standard Project Manifest
- Set clear expectations for development flow and checkpoints
- Begin implementation with clear objectives
-
During development
- Use command pattern for clear instructions
- Establish checkpoints at logical intervals
- Document code using Code Context Template
- Provide feedback on checkpoint frequency
-
End session
- Create Session Summary
- Update Project Manifest
- Document next steps
-
Resume later
- Share Project Manifest and relevant code
- Use Quick Session Resume Template
- Confirm AI's understanding before continuing
-
Repeat until project completion
By maintaining this structured approach to communication and context management, you'll maximize the effectiveness of your AI development partnership and ensure consistent progress regardless of session interruptions or context limitations.