Skill for managing long-term projects that require work across many Claude sessions. Based on Anthropic research.
** Source**: Effective harnesses for long-running agents (Anthropic Engineering, Nov 2025)
The problem this skill solves
AI agents work in discrete sessions without memory of previous work. This leads to:
- ❌ Attempts to do everything at once (one-shotting)
- ❌ Prematurely declaring the project complete
- ❌ Losing context between sessions
- ❌ Bugs and undocumented progress
Solution: Two types of agents + structured artifacts for passing context.
Orchestration architecture
┌─────────────────────────────────────────────────────────────────┐
│ ORCHESTRATION FLOW │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────┐ FIRST RUN ONLY │
│ │ INITIALIZER │─────────────────────────────┐ │
│ │ AGENT │ │ │
│ │ │ Creates: │ │
│ │ (Claude + this │ • features.json │ │
│ │ skill in init │ • progress.md │ │
│ │ mode) │ • init.sh │ │
│ └──────────────────┘ • Initial git commit │ │
│ │ ▼ │
│ │ ┌─────────────────────────────────┐ │
│ │ │ PROJECT ARTIFACTS │ │
│ │ │ ┌─────────────────────────┐ │ │
│ │ │ │ .claude/ │ │ │
│ │ │ │ ├── features.json │ │ │
│ │ │ │ ├── progress.md │ │ │
│ │ │ │ └── architecture.md │ │ │
│ │ │ │ scripts/init.sh │ │ │
│ │ │ └─────────────────────────┘ │ │
│ │ └─────────────────────────────────┘ │
│ │ ▲ │ │
│ │ │ │ │
│ │ ┌───────────────┘ │ │
│ ▼ │ ▼ │
│ ┌──────────────────┐ ┌──────────────────┐ │
│ │ CODING AGENT │───────────────▶│ CODING AGENT │ │
│ │ Session 1 │ │ Session 2 │ ... │
│ │ │ Reads: │ │ │
│ │ (Claude + this │ • progress.md │ │ │
│ │ skill in │ • features.json │ │
│ │ continue mode) │ • git log │ │ │
│ │ │ │ │ │
│ │ Updates: │ Updates: │ │ │
│ │ • 1 feature │ • 1 feature │ │ │
│ │ • progress.md │ • progress.md │ │ │
│ │ • git commit │ • git commit │ │ │
│ └──────────────────┘ └──────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
Operating modes
1. init — Initializing a new project
When to use: First run, new project.
Input data from the user:
| Parameter | Required | Description |
|---|---|---|
| Project description | ✅ | What needs to be built |
| Project type | ✅ | web-app | api | cli | library | mobile |
| Technology stack | ⚪ | React, Python, Rails... (or auto-detect) |
| Feature priorities | ⚪ | Which features are more important |
Generated artifacts:
project/
├── .claude/
│ ├── progress.md # Лог прогресса между сессиями
│ ├── features.json # 30-200 фич с статусами
│ └── architecture.md # Ключевые архитектурные решения
├── scripts/
│ └── init.sh # Setup окружения + smoke test
└── [initial git commit]
2. continue — Continuing work
When to use: Every subsequent session.
Input data: Not required (we read from artifacts).
Updated artifacts:
progress.md— a new entry is addedfeatures.json—passes: false → truefor completed features- Git commit with a descriptive message
3. status — Viewing progress
When to use: To see what has been done/what remains.
Artifact format
.claude/features.json
{
"project": "claude-clone",
"type": "web-app",
"created_at": "2025-12-02T10:00:00Z",
"total_features": 47,
"completed": 12,
"features": [
{
"id": "F001",
"category": "core",
"priority": 1,
"description": "User can send message and receive AI response",
"verification_steps": [
"Open app in browser",
"Type message in input field",
"Press Enter or click Send",
"Verify AI response appears within 5 seconds"
],
"passes": false,
"completed_at": null,
"session_id": null
},
{
"id": "F002",
"category": "core",
"priority": 1,
"description": "Conversation history persists after page reload",
"verification_steps": [
"Send a message",
"Reload the page",
"Verify conversation is still visible"
],
"passes": true,
"completed_at": "2025-12-02T14:30:00Z",
"session_id": "session-003"
}
]
}
Rules for features.json:
- ❌ NEVER delete features
- ❌ NEVER edit the description of already existing features
- ✅ ONLY change
passes: false → trueafter verification - ✅ ONLY add new features to the end of the list
.claude/progress.md
# Project Progress Log
## Project: claude-clone
**Type**: web-app
**Stack**: Next.js, TypeScript, Tailwind CSS
**Started**: 2025-12-02
---
## Session 5 | 2025-12-02 14:30 | session-005
**Focus**: Dark mode implementation
**Duration**: ~45 min
### Completed Features
- ✅ F012: Dark mode toggle button
- ✅ F013: Theme persistence in localStorage
### In Progress
- F014: System theme detection (80% done, need media query listener)
### Blockers
- None
### Technical Decisions
- Used CSS variables for theming (easier to maintain)
- Chose `prefers-color-scheme` media query over JS detection
### Next Session Should
1. Complete F014 (system theme detection)
2. Start F015 (conversation sidebar)
3. Run full E2E test suite
### Git Commits This Session
- `a3f2b1c` feat: add dark mode toggle component
- `e5d4c3b` feat: persist theme in localStorage
- `f7e8d9a` refactor: extract theme utils
---
## Session 4 | 2025-12-02 12:00 | session-004
...
scripts/init.sh
Purpose: Set up the environment so the agent can start working immediately.
Do NOT confuse with: By starting the dev server. init.sh is preparation, not startup.
What init.sh does:
- Installs dependencies (bundle/npm/yarn)
- Sets up the database (migrations, seeds)
- Copies .env files from examples
- Runs smoke tests to verify that everything works
- Outputs instructions on how to start the server
Examples for different stacks:
examples/init-nodejs.sh— Node.js / JavaScript / TypeScriptexamples/init-rails.sh— Ruby on Rails
Example structure (Ruby on Rails):
#!/bin/bash
set -e
echo " Setting up Rails environment..."
# 1. Install dependencies
bundle install
yarn install
# 2. Setup database
rails db:prepare
# 3. Copy env files
[ ! -f .env ] && [ -f .env.example ] && cp .env.example .env
# 4. Smoke tests
rails runner "puts '✅ Rails loads OK'"
rails runner "ActiveRecord::Base.connection; puts '✅ DB connection OK'"
echo "✅ Environment ready!"
echo "To start server: rails server"
Instructions for the human (operator)
How to start an INIT session
Человек → Claude:
"Инициализируй долгосрочный проект: [описание проекта].
Тип: web-app. Стек: Next.js + TypeScript."
Claude выполнит:
1. Создаст структуру .claude/ с артефактами
2. Сгенерирует 30-200 фич на основе описания
3. Создаст init.sh скрипт
4. Сделает initial git commit
How to start a CONTINUE session
Option 1 — Simple launch:
Человек → Claude:
"Продолжи работу над проектом"
Claude выполнит startup checklist автоматически.
Option 2 — Specifying a focus:
Человек → Claude:
"Продолжи проект, сфокусируйся на фичах авторизации"
Option 3 — Checking status before work:
Человек → Claude:
"Покажи статус проекта и что делать дальше"
When to end a session
The operator should end the session when:
- ⏰ 30-45 minutes of active work have passed
- ✅ 1-2 features are completed
- Claude starts making many changes without commits
- ⚠️ The context becomes long (Claude starts forgetting)
Command to end:
Человек → Claude:
"Заверши сессию. Обнови progress.md, закоммить изменения,
напиши что делать в следующей сессии."
Startup Checklist (automatic)
On every continue Claude MUST perform:
┌─────────────────────────────────────────────────────────────┐
│ SESSION STARTUP CHECKLIST │
├─────────────────────────────────────────────────────────────┤
│ 1. ☐ pwd → подтвердить рабочую директорию │
│ 2. ☐ git status → проверить чистоту репозитория │
│ 3. ☐ git log -5 → последние коммиты │
│ 4. ☐ cat .claude/progress.md → что было сделано │
│ 5. ☐ cat .claude/features.json → статус фич │
│ 6. ☐ ./scripts/init.sh → setup environment + smoke test │
│ 7. ☐ Выбрать ОДНУ фичу (highest priority, passes=false) │
│ 8. ☐ Объявить какую фичу будем делать │
└─────────────────────────────────────────────────────────────┘
Session End Checklist (automatic)
Before ending the session, Claude MUST:
┌─────────────────────────────────────────────────────────────┐
│ SESSION END CHECKLIST │
├─────────────────────────────────────────────────────────────┤
│ 1. ☐ Все изменения закоммичены (git status clean) │
│ 2. ☐ features.json обновлён (passes=true для готовых) │
│ 3. ☐ progress.md обновлён (новая запись сессии) │
│ 4. ☐ Указано что делать в следующей сессии │
│ 5. ☐ Нет TODO комментариев в коде │
│ 6. ☐ Базовый smoke test проходит │
└─────────────────────────────────────────────────────────────┘
Failure Modes & Solutions
| Problem | How we prevent it |
|---|---|
| Claude declares the project ready too early | features.json with a full list of features |
| Bugs and undocumented progress | Mandatory smoke test + progress.md |
| Features are marked as ready without testing | Verification steps in each feature |
| Time is spent understanding how to run it | init.sh script |
| Loss of context between sessions | progress.md + git log |
| Trying to do too much at once | The "1 feature per session" rule |
Usage examples
Example 1: Initializing a web-app
Человек: "Инициализируй долгосрочный проект: клон Notion с
базовыми функциями - страницы, блоки, drag-and-drop.
Тип: web-app. Стек: Next.js, TypeScript, Prisma, PostgreSQL."
Claude:
1. Создаёт .claude/features.json с ~50 фичами
2. Создаёт .claude/progress.md
3. Создаёт scripts/init.sh
4. git init && git add . && git commit -m "Initial project setup"
5. Выводит summary и рекомендации для первой continue сессии
Example 2: Continue session
Человек: "Продолжи работу"
Claude:
1. Выполняет startup checklist
2. Читает progress.md: "Session 3 закончилась на F007"
3. Читает features.json: F008 = "User can create new page"
4. Запускает init.sh, проверяет smoke test
5. Объявляет: "Буду работать над F008: создание новой страницы"
6. Реализует фичу инкрементально
7. Тестирует end-to-end
8. Обновляет features.json: passes=true
9. git commit -m "feat: implement page creation (F008)"
10. Обновляет progress.md
Example 3: Checking status
Человек: "Статус проекта"
Claude:
Project Status: notion-clone
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ Completed: 12/47 features (25%)
In Progress: F013 (block drag-and-drop)
⏭️ Next Priority: F014 (nested pages)
Recent Sessions:
• Session 5: Completed F011, F012 (block types)
• Session 4: Completed F009, F010 (page navigation)
Blockers: None
Integration with other tools
Git Workflow
- Each feature = a separate commit
- Commit message format:
feat: [description] (F###) - Use
git diffbefore commit
Testing
- For web-app: use Playwright/Puppeteer for E2E
- For API: use curl/httpie for smoke tests
- For CLI: run with test arguments
TodoWrite Integration
When continuing a session, create todos:
- [ ] Complete F### verification
- [ ] Update features.json
- [ ] Update progress.md
- [ ] Git commit
Limitations and known issues
- Vision limitations: Claude may not see browser alerts via Puppeteer
- Context pressure: With very long sessions, quality degrades
- Scope creep: Make sure Claude doesn't add features beyond the list
Links
- Source: Effective harnesses for long-running agents
- Quickstart code: anthropics/claude-quickstarts/autonomous-coding
- Claude 4 Prompting Guide: Multi-context window workflows