Back to Details

docs-keeper

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

docs-keeper

文档守护者

Maintain project documentation with clear human/agent separation. Includes planning workflow.
维护具有清晰人类/Agent分工的项目文档，包含规划工作流。

Project Structure

项目结构

project/
  AGENTS.md              ← agent instructions (project-specific)
  CLAUDE.md              ← symlink → AGENTS.md
  docs/
    README.md            ← human: project overview, setup, usage
    ARCHITECTURE.md      ← human: high-level design, domain concepts
    *.md                 ← human: guides, ADRs, onboarding
    agents/
      PLAN.md            ← agent: living project plan
      ASSUMPTIONS.md     ← agent: tracked assumptions
      notes/             ← agent: session notes
        YYYYMMDD-HHMM-slug.md
project/
  AGENTS.md              ← Agent指令（项目专属）
  CLAUDE.md              ← 符号链接 → AGENTS.md
  docs/
    README.md            ← 人类：项目概述、搭建、使用说明
    ARCHITECTURE.md      ← 人类：高层设计、领域概念
    *.md                 ← 人类：指南、架构决策记录（ADRs）、入职文档
    agents/
      PLAN.md            ← Agent：动态项目计划
      ASSUMPTIONS.md     ← Agent：跟踪假设
      notes/             ← Agent：会话笔记
        YYYYMMDD-HHMM-slug.md

Project root

项目根目录

  • AGENTS.md — project-specific agent instructions. Tech stack, commands, conventions, gotchas. Keep under 150 lines.
  • CLAUDE.md — always a symlink to AGENTS.md. Ensure this exists: 
    ln -sf AGENTS.md CLAUDE.md
  • No README.md at root. It lives in 
    docs/
    .
  • AGENTS.md — 项目专属Agent指令，包含技术栈、命令、规范、常见问题。内容控制在150行以内。
  • CLAUDE.md — 始终是AGENTS.md的符号链接。确保执行命令创建：
    ln -sf AGENTS.md CLAUDE.md
  • 根目录下无README.md，该文件存放在
    docs/
    目录中。

Human zone (
docs/*.md
)

人类区域（
docs/*.md
）

Written by humans, maintained by humans. Agents read these but don't edit unless explicitly asked.
  • docs/README.md — what the project does, how to set it up, how to use it. No agent jargon.
  • ARCHITECTURE.md — high-level design. Describe capabilities and domain concepts, not file paths.
  • Other docs as needed: ADRs, API guides, onboarding.
由人类编写和维护。Agent可阅读但除非明确要求否则不得编辑。
  • docs/README.md — 说明项目功能、搭建方法、使用方式，不含Agent相关术语。
  • ARCHITECTURE.md — 高层设计文档，描述功能和领域概念，而非文件路径。
  • 其他按需文档：架构决策记录（ADRs）、API指南、入职文档。

Agent zone (
docs/agents/
)

Agent区域（
docs/agents/
）

Written and maintained by agents. Committed to git. Survives context windows and agent rotations.
  • PLAN.md — the living project plan (see Planning below)
  • ASSUMPTIONS.md — document assumptions before acting. Update as confirmed or invalidated.
  • notes/ — timestamped session notes (see Session Notes below)
由Agent编写和维护，提交至Git。可跨越上下文窗口和Agent轮换周期留存。
  • PLAN.md — 动态项目计划（见下文“规划”部分）
  • ASSUMPTIONS.md — 行动前记录假设，在假设被确认或推翻时更新。
  • notes/ — 带时间戳的会话笔记（见下文“会话笔记”部分）

Planning

规划

Before any multi-step work, create or update 
docs/agents/PLAN.md
.
在进行任何多步骤工作前，创建或更新
docs/agents/PLAN.md
。

Brainstorming (before the plan)

头脑风暴（规划前）

Don't jump into planning. Understand first:
  1. Explore context — read existing docs, code, recent commits
  2. Ask clarifying questions — one at a time, understand purpose/constraints/success criteria
  3. Propose 2-3 approaches — with trade-offs and your recommendation
  4. Present design in sections — scaled to complexity, get approval after each section
  5. Save design — write validated design to 
    docs/agents/PLAN.md
Do NOT write code until the design is approved. Every project goes through this, even "simple" ones. Simple projects are where unexamined assumptions waste the most work.
不要直接开始规划，先理解需求：
  1. 探索上下文 — 阅读现有文档、代码、近期提交记录
  2. 提出澄清问题 — 一次一个问题，明确目标/约束/成功标准
  3. 提出2-3种方案 — 说明各方案的权衡及你的推荐
  4. 分模块展示设计 — 复杂度适配模块划分，完成每个模块后获取批准
  5. 保存设计 — 将已验证的设计写入
    docs/agents/PLAN.md
在设计获得批准前不得编写代码。所有项目都需遵循此流程，即使是“简单”项目。简单项目中未经审视的假设最容易导致无效工作。

Plan format

计划格式

Plans are bite-sized tasks. Each task is one action (2-5 minutes):
markdown
undefined
计划需拆分为小型任务，每个任务对应一个操作（2-5分钟完成）：
markdown
undefined

[Feature] Implementation Plan

[功能] 实施计划

Goal: One sentence. Approach: 2-3 sentences. Tech: Key technologies/libraries.
目标： 一句话描述。 方案： 2-3句话说明。 技术栈： 核心技术/库。

Task 1: [Component]

任务1：[组件]

Files:
  • Create: 
    exact/path/to/file.go
  • Modify: 
    exact/path/to/existing.go
  • Test: 
    exact/path/to/file_test.go
Steps:
  1. Write failing test
  2. Run test, verify it fails
  3. Write minimal implementation
  4. Run test, verify it passes
  5. Commit
Verify: 
go test ./... -run TestSpecificThing

Rules:
- Exact file paths, always
- Complete code in plan (not "add validation")
- Exact commands with expected output
- Each step is one action, not a paragraph
文件：
  • 创建：
    exact/path/to/file.go
  • 修改：
    exact/path/to/existing.go
  • 测试：
    exact/path/to/file_test.go
步骤：
  1. 编写失败测试用例
  2. 运行测试，确认测试失败
  3. 编写最小化实现代码
  4. 运行测试，确认测试通过
  5. 提交代码
验证： 
go test ./... -run TestSpecificThing

规则：
- 必须使用精确文件路径
- 计划中需包含完整代码（而非“添加验证”这类模糊描述）
- 精确命令及预期输出
- 每个步骤对应一个操作，而非段落

Execution

执行

Execute plans in batches (3 tasks at a time):
  1. Follow each step exactly
  2. Run verifications as specified
  3. After each batch: report what was done, show verification output, wait for feedback
  4. Apply feedback, continue next batch
Stop and ask when:
  • Hit a blocker (missing dep, test fails, instruction unclear)
  • Plan has gaps
  • Verification fails repeatedly
  • Don't guess through blockers
分批执行计划（每次3个任务）：
  1. 严格遵循每个步骤
  2. 按指定方式执行验证
  3. 每批任务完成后：汇报已完成工作、展示验证结果、等待反馈
  4. 根据反馈调整，继续下一批任务
遇到以下情况需停止并询问：
  • 遇到阻塞（依赖缺失、测试失败、指令不明确）
  • 计划存在漏洞
  • 验证反复失败
  • 不要自行猜测解决阻塞问题

Session Notes

会话笔记

Write notes to 
docs/agents/notes/YYYYMMDD-HHMM-slug.md
when you learn something worth preserving:
  • Lessons learned from debugging
  • Architecture decisions and rationale
  • Failed approaches and why they didn't work
  • Investigation findings (API quirks, library gotchas)
  • Mistakes and how to avoid them
Keep notes concise. Future agents read these for context.
当学到值得留存的内容时，写入
docs/agents/notes/YYYYMMDD-HHMM-slug.md
：
  • 调试过程中获得的经验
  • 架构决策及理由
  • 失败的方案及其原因
  • 调研发现（API特性、库的常见问题）
  • 错误案例及规避方法
笔记需简洁，供后续Agent获取上下文信息。

Session Discipline

会话规范

Start: Read 
docs/agents/PLAN.md
and 
AGENTS.md
.
End: Update plan if anything changed. Write a note if you learned something.
开始时： 阅读
docs/agents/PLAN.md
和
AGENTS.md
。
结束时： 若有变更则更新计划，若学到新内容则撰写笔记。

Keeper Behavior

守护者行为

When invoked as docs-keeper (or when documentation is stale):
  1. Ensure structure — AGENTS.md exists, CLAUDE.md is symlinked, 
    docs/agents/
    exists
  2. Audit — check all docs exist, are accurate, aren't contradicting code
  3. Fix — update what you can (agents zone only, unless asked for human zone)
  4. Flag — report what needs human attention
  5. Trim — AGENTS.md should stay under 150 lines. Move overflow to 
    docs/
当以docs-keeper身份被调用（或文档过时）时：
  1. 确保结构完整 — 检查AGENTS.md是否存在、CLAUDE.md是否为符号链接、
    docs/agents/
    目录是否存在
  2. 审计 — 检查所有文档是否存在、内容是否准确、与代码是否矛盾
  3. 修复 — 更新可修改内容（仅Agent区域，除非被要求修改人类区域）
  4. 标记 — 汇报需要人类处理的事项
  5. 精简 — AGENTS.md内容需控制在150行以内，超出部分移至
    docs/
    目录

Rules

规则

  • One code example beats three paragraphs
  • Describe capabilities, not file paths (paths go stale)
  • Don't document what agents already know (language syntax, common patterns)
  • Create 
    docs/agents/
    and subdirectories if they don't exist
  • Never edit human zone docs without explicit permission
  • 一个代码示例胜过三段文字描述
  • 描述功能而非文件路径（路径易过时）
  • 无需记录Agent已知内容（如语言语法、通用模式）
  • 若
    docs/agents/
    及其子目录不存在则创建
  • 未经明确许可不得修改人类区域文档