为什么值得关注

它解决了AI助手在会话间遗忘上下文的根本问题，通过最小化但明确的文档系统及多层强制机制（CLAUDE.md、技能指令、会话钩子），确保新会话的助手总能无缝衔接上次的工作。

适合谁使用

使用Claude Code、Codex或Cursor等AI编程助手的开发者
管理多个AI辅助项目的团队
希望实现可复现助手工作流的工程师
需要统一项目状态交接的项目负责人

典型使用场景

无需重复解释项目目标、状态和下一步即可启动新会话
通过HANDOFF.md的YAML头信息维护项目状态的单一事实来源
管理包含多个项目的工作区，自动生成分类索引和全局总览
通过会话开始/结束钩子和命令技能强制助手遵守文档规范

项目优势

极其简洁：5个文件各司其职，30秒即可完成设置
多层强制：上下文注入、分步技能指令、以及阻止未更新HANDOFF.md的会话结束钩子
工作区生成器可从PowerShell或Python运行，无依赖，输出字节一致
纯Markdown文件适用于任何AI助手；可选钩子层增强Claude Code体验

使用前须知

完整强制钩子需要Python 3.7+及首次授权
钩子和技能层仅限Claude Code使用；其他助手只能利用文件约定
依赖用户在每次会话结束时手动更新HANDOFF.md

README 快速开始

Dear Agent,

English | 한국어

A tiny, opinionated documentation system for projects built with AI coding agents (Claude Code and friends) — the letter your project leaves for the next session's agent.

The problem: agents forget everything between sessions. Every new session starts with you re-explaining what the project is, where it stopped, and what to do next.

The fix: five small markdown files per project — each with exactly one job, zero overlap — plus a generator that turns them into a workspace-wide project map once you have many projects.

Tier 1 — one project (30 seconds)

Copy the five files from _templates/ into your repo and fill them in:

File	Job	Update when
`PLAN.md`	goals, scope, tech decisions	decisions change
`HANDOFF.md`	current state: last work / next steps / blockers, + status frontmatter	every session end
`LOG.md`	one line per notable change	features/fixes land
`README.md`	how to run it	run steps change
`CLAUDE.md`	agent ops guide: commands, code map, pitfalls	build/structure changes

The heart is HANDOFF.md. Its YAML frontmatter is the single source of truth for project state:

---
status: 개발            # 기획(planning) | 개발(building) | 운영(live) | 보류(paused)
updated: 2026-07-05
summary: one-line status
repo: org/name          # delete this line if no remote
---

An agent reads it at session start and knows exactly where to pick up — no re-explaining.

Using an agent other than Claude Code? Copy or symlink CLAUDE.md to AGENTS.md.

Tier 2 — many projects (a workspace)

When projects multiply, this repo doubles as a workspace template: category folders hold projects, and a generator scans every HANDOFF.md frontmatter to build tables of contents.

workspace/
├─ OVERVIEW.md          ← generated: map of ALL projects
├─ CONVENTIONS.md       ← the single rulebook
├─ apps/                ← a category folder (any name)
│  ├─ _INDEX.md         ← generated: projects in this category
│  ├─ todo-api/         ← a project (the 5 files + code)
│  └─ web-dashboard/
└─ build-index.ps1 / build-index.py

Run either generator — they produce byte-identical output (CI-enforced), no dependencies:

powershell -File ./build-index.ps1    # Win

项目描述

Dear agent: everything you need to resume this project. A 5-file docs convention + workspace template for AI coding agents.

dear-agent