popsicle

Popsicle

Agent 原生的入门文档生成器。发现。映射。生成。适配。验证。循环。

目的： 让任何代码仓库都适合 Agent 使用。一个毫无上下文的全新 AI Agent 应当能够阅读文档并开始工作，而无需先阅读源代码。

适合 Agent 使用的输出。 Popsicle 生成的每项产物——覆盖率映射、健康基线、生成的文档、Agent 适配器——都经过专门设计，让全新的 AI Agent 能够独立浏览你的代码仓库，而不只是供人快速浏览 README。

通过 npx 安装：

npx skills add fellowship-dev/dogfooded-skills/skills/ops/popsicle

适用场景

• 新代码仓库入门： 从零开始创建 Agent 可读的文档。
• 重大重构后： 确认文档仍与实际情况一致。
• 定期健康检查： 在文档腐化不断加剧之前及时发现。
• 将代码仓库交给 Agent 前： 确认文档能为全新的 Agent 提供独立工作的充足信息。
• 多工具团队： 使用 --agents 为 Cursor、Copilot 和 Codex 生成适配器文件。

防作弊约束

研究过程中发现的内容是答案。代码仓库文档是试题。全新的验证会话是学生。

发现阶段的产物（知识映射）必须存放在 /tmp，绝不能放进代码仓库。验证会话必须完全无法访问发现阶段的产物。如果它们能看到你的发现，测试就毫无意义。

---

文档类型——内容各归何处

Agent 需要三类文档。Popsicle 会强制保持它们相互独立：

1. CLAUDE.md——Agent 指令（≤80 行）

入口文件。Agent 会先阅读它。它回答：“这是个什么代码仓库？我该如何在其中工作？必须遵守哪些规则？”

适合放在此处的内容：

• 项目身份（一句话说明项目是什么、使用什么技术栈）
• 如何安装、运行、测试、部署（仅命令，不作说明）
• 关键规则和约束（违反后会导致故障的事项）
• 指向 docs/ 深入参考资料的链接

不适合放在此处的内容：

• 架构说明（→ docs/architecture.md）
• API 参考（→ docs/api.md）
• 超过 5 行的配置/环境变量表（→ docs/configuration.md）
• 操作手册或故障排查内容（→ docs/runbook.md）
• 历史、背景或“我们为何构建它”（→ README.md 或不放入文档）

行数上限：≤80 行。 如果修改后 CLAUDE.md 超过 80 行，请重构：将详细内容移至 docs/，并用一行链接替代。使用 wc -l CLAUDE.md 统计行数。

2. docs/*.md——参考文档

Agent 在处理特定领域时会查阅的深入资料。每个文件只涵盖一个主题。Agent 应当仅凭文件名就能找到合适的文件。

标准文件（仅创建代码仓库所需的文件）：

• docs/architecture.md——系统边界、数据流、关键抽象、服务映射
• docs/api.md——路由、端点、请求/响应结构
• docs/configuration.md——环境变量、功能开关、包含全部选项说明的配置文件
• docs/workflows.md——开发工作流、CI/CD、部署流程、发布步骤
• docs/data-model.md——数据库架构、关键表、关系
• docs/glossary.md——代码中不明显的领域术语（仅在需要时创建）
• docs/runbook.md——常见问题的调试方法、运维流程

规则：

• 每个文件只涵盖一个主题。如果文件超过 200 行，请拆分。
• 文件名必须能清楚说明内容——Agent 根据文件名选择要阅读的文件。
• 不要创建 docs/misc.md 或 docs/notes.md——如果内容没有明确主题，就不应放在这里。
• 概念跨越多个领域时，请在文档文件之间添加链接。

3. README.md——面向人类的文档（不要修改）

README.md 面向人类：徽章、截图、营销文案、贡献指南。Popsicle 不会修改 README.md。 如果关键信息仅存在于 README.md，且应纳入 Agent 文档，请将相关事实复制到对应的 docs/ 文件或 CLAUDE.md 中——不要重构 README。

---

指令

0. 设置

REPO_ROOT=$(git rev-parse --show-toplevel)
REPO_NAME=$(basename $(git remote get-url origin) .git)
TODAY=$(date +%Y-%m-%d)
ITERATION=1
MAX_ITERATIONS=5
PASS_THRESHOLD=80

解析标志：

• --loop — 运行完整循环，直到通过率 >= 80% 或达到最大迭代次数
• --agents — 生成 Agent 适配器文件（阶段 2.5）
• --canonical agents — 将 AGENTS.md 设为事实来源；CLAUDE.md 符号链接到它

自动检测 --agents 行为：如果仓库中已存在 .cursor/ 或 .github/copilot-instructions.md，则视为已设置 --agents。

每次迭代都必须完成所有阶段。 不要在验证后停止——始终进行评分、报告，并决定是否循环。如果上下文有限，评分内容尽量简洁（每个概念一行）。

---

阶段 1：发现（构建答案键）

系统地扫描仓库。构建一张知识图谱，列出 Agent 应当能够从优质文档中了解到的内容。

扫描内容：

• 入口点（main、index、app、CLI 入口点）
• 如何安装、运行和测试（具体命令，而不只是说明这些命令存在）
• API 路由和端点
• 配置文件（环境变量、功能标志、部署配置）
• 重要抽象（关键类、模块、模式）
• 架构（服务边界、数据流、外部依赖）
• 开发工作流（CI、部署、发布流程）
• 无法从代码中直接看出的领域专用术语

按文档类型对每个概念进行分类——Agent 应该从哪里找到这些内容？

类别	目标文件
项目身份、技术栈、运行/测试命令、关键规则	CLAUDE.md
系统设计、数据流、服务边界	docs/architecture.md
路由、端点、请求/响应	docs/api.md
环境变量、配置文件、功能标志	docs/configuration.md
开发工作流、CI/CD、部署、发布	docs/workflows.md
数据库架构、关键表	docs/data-model.md
领域术语	docs/glossary.md

每次迭代选择 5–10 个概念。 在不同迭代中轮换，最终覆盖整个仓库。不要重复已通过的概念。

将知识图谱写入临时文件：

KNOWLEDGE_MAP="/tmp/popsicle-knowledge-$(date +%s).json"

python3 -c "
import json, sys
concepts = [
    {
        'id': 'concept-1',
        'category': 'architecture',
        'target_file': 'docs/architecture.md',
        'name': 'Short name',
        'description': 'What an agent should know about this',
        'evidence': 'Where you found it in the code (file:line)',
        'question': 'Question to ask the validation session',
        'nav_question': 'Which doc file would you read to learn about this?'
    },
    # ... 5-10 concepts
]
with open('$KNOWLEDGE_MAP', 'w') as f:
    json.dump({'repo': '$REPO_NAME', 'iteration': $ITERATION, 'concepts': concepts}, f, indent=2)
"

此文件是答案键。它保留在 /tmp 中。切勿提交。

---

阶段 1.5：覆盖范围图

完成发现后，编写覆盖范围图，让人类和 Agent 都能一目了然地看到哪些内容已有文档记录，哪些尚未记录。

编写（或覆盖）docs/coverage-map.md：

# Coverage Map — {REPO_NAME}

> Generated by popsicle on {TODAY} (iteration {N}).
> ✓ = documented  ✗ = gap  ~ = partial

## {top-level-area/}

- ✓ `src/index.ts` — entry point, startup sequence
- ✓ `src/routes/` — API routes (see docs/architecture.md)
- ✗ `src/workers/` — background job processing (undocumented)
- ~ `src/models/` — data models exist in README but schema not captured

## {another-area/}

- ✗ `scripts/deploy.sh` — deployment procedure (gap)
- ✓ `.env.example` — environment variables documented in CLAUDE.md

规则：

• 使用与目录结构对应的层级文件树顺序。
• 为发现阶段涉及的每个文件/领域创建条目。
• 不要为未扫描的领域虚构条目。
• 只有在验证环节有可能从文档中找到答案时才标记 ✓。如果不确定，则标记 ~。

与文档更改一同提交（阶段 2 的提交也包含此文件）。

---

阶段 2：生成（改进文档）

阅读现有文档：CLAUDE.md、docs/ 目录、README.md（仅供参考，不可修改）。

对于知识图谱中的每个概念：

1. 目标文件是否存在？如果不存在，创建该文件并添加 # Title 标题。
2. 该概念是否已在正确的位置记录？如果是，则跳过。
3. 如果记录在错误的位置（例如，架构细节记录在 CLAUDE.md 中），则将其移至正确位置。
4. 如果缺失，则将其写入目标文件。

放置完所有概念后，确保符合篇幅限制：

CLAUDE_LINES=$(wc -l < CLAUDE.md 2>/dev/null || echo 0)
if [ "$CLAUDE_LINES" -gt 80 ]; then
  echo "CLAUDE.md is $CLAUDE_LINES lines — over 80-line budget. Refactor."
fi

如果 CLAUDE.md 超过 80 行：

1. 找出属于参考资料的章节（超过 5 行的表格、详细说明、示例）。
2. 将这些内容移至相应的 docs/ 文件。
3. 替换为一行指引：See [docs/configuration.md](docs/configuration.md) for full env var reference.
4. 重新检查行数。

CLAUDE.md 结构模板（根据仓库情况调整，不要强行添加不适用的章节）：

# {Repo Name}

{One sentence: what this is and what stack.}

## Quick Start

{install, run, test commands — no prose, just the commands}

## Key Rules

{Things that break if violated — max 5 bullets}

## Project Structure

{Only if non-obvious — 5-10 lines max showing key directories}

## Reference

- [Architecture](docs/architecture.md) — {one-line summary}
- [Configuration](docs/configuration.md) — {one-line summary}
- [API](docs/api.md) — {one-line summary}

健康基线

编写（或更新）docs/health-baseline.md。使用类别，而非分数：

# Doc Health Baseline — {REPO_NAME}

> Last updated by popsicle on {TODAY}.

## Architecture

**Docs exist:** `docs/architecture.md`, CLAUDE.md §Architecture
**Missing:** service dependency graph, data flow for async jobs
**Companion skills installed:** none

## API Contracts

**Docs exist:** README API section
**Missing:** request/response schemas for /auth routes
**Companion skills installed:** none

## Dev Setup

**Docs exist:** README §Getting Started
**Missing:** `.env` values required for local OAuth
**Companion skills installed:** hookshot (enforces freshness on commit)

## Deployment

**Docs exist:** none
**Missing:** deploy command, required secrets, rollback procedure
**Companion skills installed:** none

此文件是持续监控的长期基础。其他技能（entropy-check、hookshot）可以使用它。

生成的文档

将自动提取的事实写入 docs/generated/。这些文件是临时的——每次迭代都会重新生成。生成这些文件是为了让 Agent 无需重新发现这些信息。

始终包含“最后更新”标题：

仅在适用时生成以下文件：

• docs/generated/env-vars.md — 代码库中发现的所有环境变量（.env.example、process.env.*、os.environ 等）
• docs/generated/api-routes.md — 从路由器文件中提取的所有 API 路由
• docs/generated/db-schema.md — 数据库架构摘要（如果存在 ORM 或迁移文件）

提交所有文档更改（包括 coverage-map.md 和 health-baseline.md）：

git add CLAUDE.md docs/
git commit -m "docs: popsicle iteration $ITERATION — structured agent docs

Concepts targeted: [list the concept names]
Coverage map updated. Health baseline updated."

---

阶段 2.5：Agent 适配器

生成文档后，创建与 Agent 无关的入口，以便任何 AI 工具都能接入此代码库。

默认（始终执行）

如果 AGENTS.md 尚不存在，则将其创建为指向 CLAUDE.md 的符号链接：

if [ ! -e "$REPO_ROOT/AGENTS.md" ]; then
  ln -s CLAUDE.md "$REPO_ROOT/AGENTS.md"
  git add "$REPO_ROOT/AGENTS.md"
  git commit -m "docs: add AGENTS.md symlink for Codex compatibility"
fi

如果设置了 --canonical agents 标志，则反转这一关系——将 AGENTS.md 设为真实文件，并将 CLAUDE.md 设为符号链接。仅当这两个文件都还不是符号链接时才执行此操作。

使用 --agents 标志（或自动检测）

自动检测：如果代码库中已存在 .cursor/ 或 .github/copilot-instructions.md，则按传入了 --agents 的情况处理。

在编写任何适配器之前，先检查它是否已存在且包含自定义内容。 如果文件已存在，且不包含 generated by popsicle 标记，则跳过该文件——不要覆盖自定义配置。

编写 .github/copilot-instructions.md：

# {REPO_NAME} — Copilot Instructions

See CLAUDE.md for project identity and docs/ for reference material.
Key docs: docs/architecture.md, docs/coverage-map.md, docs/health-baseline.md

编写 .cursor/rules/project.mdc：

---
description: Project onboarding for {REPO_NAME}
alwaysApply: true
---

See CLAUDE.md for project identity and docs/ for reference material.
Key docs: docs/architecture.md, docs/coverage-map.md, docs/health-baseline.md

适配器规则：

• 适配器只是轻量指引，不应重复内容。
• CLAUDE.md 始终是唯一可信来源（除非设置了 --canonical agents）。
• 绝不要覆盖现有的自定义配置（写入前检查是否包含 generated by popsicle 标记）。

提交适配器（如果有编写）：

git add .github/copilot-instructions.md .cursor/rules/project.mdc 2>/dev/null
git diff --cached --quiet || git commit -m "docs: add agent adapter files (popsicle)"

---

阶段 3：验证（使用全新会话测试）

关键：验证会话必须无法看到知识图谱。 它已存放在 /tmp 中（不在代码库内），因此全新会话无法看到它。

每个概念进行两类验证：

RESULTS_DIR="/tmp/popsicle-results-$(date +%s)"
mkdir -p "$RESULTS_DIR"

测试 A——内容验证（Agent 能否根据文档回答？）：

claude -p "You are examining the repository at $REPO_ROOT. \
Using ONLY the documentation in this repo (CLAUDE.md, docs/*.md), \
answer this question. Do not read source code — only docs. \
If the docs don't cover this, say 'NOT DOCUMENTED'. \
\
Question: [concept.question]" \
  --model sonnet --output-format text \
  2>/dev/null > "$RESULTS_DIR/concept-N-content-1.txt"

每个概念运行 2 个相互独立的内容验证会话。

测试 B——导航验证（Agent 能否找到该查看的位置？）：

claude -p "You are examining the repository at $REPO_ROOT. \
Look at the documentation files available (CLAUDE.md, docs/*.md). \
Do NOT read the full contents — only look at file names and headers. \
\
Question: Which specific doc file would you open to learn about: [concept.nav_question]? \
Answer with just the file path." \
  --model sonnet --output-format text \
  2>/dev/null > "$RESULTS_DIR/concept-N-nav.txt"

每个概念运行 1 个导航验证会话。

最多并行运行 3 个会话（在后台运行并使用 wait）。并发会话不得超过 3 个——小型机器可能会因内存耗尽而崩溃。

---

阶段 4：评分 + 过时检测

评分

对每个概念从两个维度评分：

内容分数（来自测试 A）：

• PASS（2/2）：两个会话都能根据文档正确回答。
• WEAK（1/2）：一个会话答对，另一个没有。
• FAIL（0/2）：两个会话都无法回答。

导航分数（来自测试 B）：

• HIT：Agent 指向了正确的文件（与知识图谱中的 target_file 一致）。
• MISS：Agent 指向了错误的文件，或找不到文件。

综合判定：

• PASS：内容 PASS + 导航 HIT
• PARTIAL：内容 PASS + 导航 MISS（信息存在但难以找到），或内容 WEAK + 导航 HIT
• FAIL：内容 FAIL（无论导航结果如何），或内容 WEAK + 导航 MISS

过时检测

评分后，通过将文档中的说法与实际代码进行比较来检查内容是否过时。阅读本轮生成或更新的文档，并检查是否存在事实不符。

检查内容：

• 端口号（例如，文档写着“端口 3000”，但代码使用 PORT=4000）
• 环境变量名称（例如，文档写着 DATABASE_URL，但代码读取的是 DB_CONNECTION_STRING）
• 文件路径（例如，文档引用 src/server.js，但该文件已移至 src/app.js）
• 命令语法（例如，文档写着 npm start，但 package.json 中的脚本已更改）
• 版本号（例如，文档指定 Node 16，但 .nvmrc 中写的是 20）

对于发现的每处不符，都添加一个 STALE 条目：

{
  "type": "STALE",
  "doc_claim": "port 3000 (README line 42)",
  "actual": "PORT env var defaults to 4000 (src/config.ts:8)",
  "fix": "Update README to reference PORT env var"
}

将 STALE 项添加到报告（Phase 5）的差距列表中。

计算通过率（仅统计 PASS；PARTIAL 按一半计；STALE 项不影响通过率，单独跟踪）：

SCORE=$((PASS_COUNT * 100 + PARTIAL_COUNT * 50))
PASS_RATE=$((SCORE / TOTAL_CONCEPTS))

---

Phase 5：报告

REPORT="$REPO_ROOT/docs/popsicle-report-${TODAY}.md"

# Popsicle Report — {REPO_NAME}

**Date**: {TODAY}
**Iteration**: {N}
**Concepts tested**: {count}
**Pass rate**: {PASS_COUNT}/{TOTAL} ({PCT}%)
**Stale claims found**: {STALE_COUNT}

## Doc Structure

| File | Lines | Status |
|------|-------|--------|
| CLAUDE.md | {n} | {ok / over budget} |
| docs/architecture.md | {n} | {exists / created / n/a} |
| docs/configuration.md | {n} | {exists / created / n/a} |
| ... | | |

## Results

| # | Concept | Target File | Content | Nav | Verdict |
|---|---------|-------------|---------|-----|---------|
| 1 | {name}  | docs/arch.. | PASS    | HIT | PASS    |
| 2 | {name}  | CLAUDE.md   | WEAK    | HIT | PARTIAL |
| 3 | {name}  | docs/api..  | FAIL    | MISS| FAIL    |

## Gaps Remaining

- **{concept}**: {why it failed — what's missing or misplaced}
- ...

## Staleness



- **{doc_claim}** in `{file}`: actual value is `{actual}`. Fix: {fix}
- ...

## Missing Knowledge



- **Business rules**: {e.g., "pricing tiers defined in Notion, not in code"}
- **External credentials**: {e.g., "Stripe webhook secret — ask ops team"}
- **Deployment procedures**: {e.g., "staging deploy requires VPN + manual approval"}
- ...

## Doc Changes This Iteration

- Updated `CLAUDE.md`: added {what}
- Updated `docs/architecture.md`: added {what}
- Updated `docs/coverage-map.md`: reflects new scan
- Updated `docs/health-baseline.md`: added {category} section
- Created `docs/generated/env-vars.md`
- ...

## Companion Skills

These skills complement popsicle for ongoing doc health:

- **hookshot** — enforces doc freshness via commit hooks
  `npx skills add fellowship-dev/dogfooded-skills/skills/ops/hookshot`
- **entropy-check** — periodic doc drift sensor
  `npx skills add fellowship-dev/dogfooded-skills/skills/ops/entropy-check`
- **trash-truck** — investigates material product, code, and operational surfaces for evidence-backed retirement; scheduled runs only maintain the review record
  `npx skills add fellowship-dev/dogfooded-skills/skills/ops/trash-truck`
- **issue-to-prd** — turns an issue into a committed spec with owner questions before implementation
  `npx skills add fellowship-dev/dogfooded-skills/skills/ops/issue-to-prd`

提交报告：

git add "docs/popsicle-report-${TODAY}.md"
git commit -m "docs: popsicle report — iteration $ITERATION, ${PASS_RATE}% pass rate"

---

Phase 6：循环或停止

if [ "$PASS_RATE" -ge "$PASS_THRESHOLD" ]; then
  echo "Pass rate ${PASS_RATE}% >= ${PASS_THRESHOLD}%. Docs are agent-ready. Stopping."
  exit 0
fi

if [ "$ITERATION" -ge "$MAX_ITERATIONS" ]; then
  echo "Hit max iterations ($MAX_ITERATIONS). Pass rate: ${PASS_RATE}%. Review remaining gaps manually."
  exit 0
fi

ITERATION=$((ITERATION + 1))

如果通过率低于阈值且仍有剩余迭代次数：

1. 从报告中读取 FAIL、PARTIAL 和 STALE 概念。
2. 对于导航 MISS：调整结构——将内容移至更容易发现的位置，或重命名文件。
3. 对于内容 FAIL：改进目标文件中的文档。立即修复 STALE 声明。
4. 返回 Phase 2。

---

清理

所有迭代完成后：

rm -f /tmp/popsicle-knowledge-*.json
rm -rf /tmp/popsicle-results-*

发现阶段的产物是临时的。报告和文档更改会提交。

---

使用模式

单次运行（单次迭代，仅生成报告）：

/popsicle

循环运行（持续迭代，直到通过率 >= 80% 或达到最多 5 次迭代）：

/popsicle --loop

使用 Agent 适配器（生成 Copilot/Cursor 文件）：

/popsicle --agents

使用规范 AGENTS.md（AGENTS.md 是事实来源，CLAUDE.md 通过符号链接指向它）：

/popsicle --canonical agents

Crew 任务（通过 Pylot 分派）：

curl -X POST "$PYLOT_DISPATCH_URL" \
  -H "Authorization: Bearer $PYLOT_DISPATCH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"agent":"crew.lead","task":"Run popsicle in loop mode on this repo. Commit doc improvements and reports.","repo":"org/repo"}'

---

设计原则

1. **无需评分标准。**该技能通过阅读代码来发现重点，无需预先配置。
2. **通过架构防止作弊。**发现阶段的产物存放在 /tmp 中。验证会话是全新的。测试结果可信。
3. **文档在每轮迭代中不断完善。**这不仅是测量，还会主动填补差距。
4. **全新会话是判断标准。**如果全新的 Agent 无法从文档中获取所需信息，那么文档就有问题。
5. **优先循环迭代。**单次迭代很有用；进行五次有针对性的修复，效果会大不相同。
6. **面向 Agent。**输出专为自主 Agent 而设计，不只是面向人类。每份文档都应回答：“全新的 Agent 能否在此仓库中独立工作？”
7. **覆盖率优先于完整性。**展示已知差距的覆盖图，胜过声称内容完整的文档。相比虚假的自信，Agent 更需要如实说明差距。
8. **松散耦合。**每项配套技能都能独立工作。Popsicle 会生成产物（coverage-map.md、health-baseline.md），其他技能可以按需使用。