操作记忆 FiredMosquito831/working-notes

working-notes

你的 AI 编程智能体一直缺的那本操作手册。

一个可移植的智能体技能（SKILL.md），把任意仓库变成有编排的项目：先调查再动手，写规格，记录决策，只让一个实现者干活，每条结论都自己核实，并留下能跨会话存活的队列、交接和教训日志。

可在 Claude Code、Codex、Cursor、GitHub Copilot、Gemini CLI、OpenCode、 Antigravity、Cline、Qwen Code、Kilo Code、Windsurf、Command Code 和 DeepSeek Harness 中运行，也支持任何能读取 SKILL.md 的 harness。

快速开始 ·安装 ·它会创建什么 ·规则 ·工作原理 ·常见问题

目录

- 为什么你的智能体需要它
- 工作原理
- 快速开始
- 安装
- 终端与命令行 harness
- 编辑器与 IDE harness
- 手动安装
- 它会创建什么
- 规则
- 对比
- 适合谁用
- 常见问题
- 文档
- 仓库结构

为什么你的智能体需要它

每次 AI 编码会话都开局惊艳，收尾失忆。不是模型太弱，而是仓库里没有任何东西把工作串起来：

- 上下文随聊天一起消失。 下次会话重新推导方案，重新问同样的问题，重新犯同样的错。
- 「做完了」只是「智能体自己说的」。 没人核对合并、标签、产物、diff 或线上系统。
- 并行智能体互相撞车。 两个实现者，一个版本文件，一次发布翻车。调研和构建糊成一团，变成一个没有边界的提示词。
- 决策蒸发。 周二做的选择，周五被悄悄推翻，因为理由从来没写下来。

working-notes 补上缺失的那一层：仓库内的操作手册、有约束力的 PR 队列、带日期的工作交接、验收契约。智能体每次会话开始时先读它。你不用再重复自己，智能体也不再凭空发挥。

一条命令安装技能。一条命令初始化项目。此后每次会话都从仓库里的文件跑起来。

工作原理

这个循环刻意做得枯燥：

1. 先讨论，再动手。 只要超出字面意义上的小请求，一律先做只读调研，而不是直接改代码。
2. 写规格。 编号列出发现、选项和用大白话写的问题，每条都附建议。
3. 记录决策。 你的一行回答会变成规格里带约束力的 USER DECISIONS 区块。
4. 派一个实现者。 给它任务简报、worktree、版本号、验收标准和明确的「不在范围内」清单。
5. 你自己验收。 合并 SHA、标签、产物摘要、冻结文件 diff、CI 状态、截图、一次真正干活的线上调用。
6. 写下来。 队列行翻转，发布历史加一行，记录经验教训，刷新工作交接。

完整方法见 工作原理。

快速开始

需要 Node.js 18+ 和 git。安装器把 SKILL.md 及其模板复制到你的 harness 已经在读的目录里。不会向任何地方发送数据。

npm

npx -y agent-working-notes install
也可以装一次，之后每个 shell 都能直接用这个二进制：

npm install -g agent-working-notes
working-notes install

npm 包与最新 GitHub release 保持一致，从打了 tag 的 commit 发布。二进制名是 working-notes。

直接从 GitHub 安装

GitHub 这条路始终取当前 main，中间不经过 npm 发布：

npx -y github:FiredMosquito831/working-notes install

两种方式都会探测你机器上的 harness，并明确打印技能装到了哪里。想自己指定：

npx -y agent-working-notes install --agent claude-code,codex

然后打开你的项目，开一个会话：

/working-notes init

或者直接说：「set up working notes for this repo」。

各平台一行命令

macOS / Linux / WSL / Git Bash

curl -fsSL https://raw.githubusercontent.com/FiredMosquito831/working-notes/main/install.sh | sh

Windows PowerShell

irm https://raw.githubusercontent.com/FiredMosquito831/working-notes/main/install.ps1 | iex

两个包装脚本都会把所有选项原样转给同一个安装器。

Claude Code 插件

Claude Code 用户也可以把它当插件装：

/plugin marketplace add FiredMosquito831/working-notes
/plugin install working-notes@firedmosquito

或者在 shell 里：

claude plugin marketplace add FiredMosquito831/working-notes
claude plugin install working-notes@firedmosquito

插件会把仓库里的技能加载为 /working-notes（也带命名空间 /working-notes:working-notes）。插件方式用 /plugin update working-notes 更新。

安装

一个安装器，通吃所有 harness。下面每条命令都完整、可直接复制粘贴。它把技能目录（SKILL.md + templates/）复制进 harness 本来就会读取的目录，并记录装了什么，这样更新和卸载都安全。

给机器上探测到的每个 harness 都装上：

npx -y agent-working-notes install

终端与命令行 harness

| Harness | 安装命令 | 调用方式 |
| Claude Code | npx -y agent-working-notes install --agent claude-code | /working-notes |
| OpenAI Codex | npx -y agent-working-notes install --agent codex | /skills，或用 $ 提及 |
| OpenCode | npx -y agent-working-notes install --agent opencode | 原生 skill 工具 |
| Gemini CLI | npx -y agent-working-notes install --agent gemini | 自动 activate_skill |
| DeepSeek Harness (dsh) | npx -y agent-working-notes install --agent deepseek | 技能目录 |
| Qwen Code | npx -y agent-working-notes install --agent qwen | 自动 |
| Command Code | npx -y agent-working-notes install --agent commandcode --scope project | 自动 |
| Antigravity CLI (agy) | npx -y agent-working-notes install --agent antigravity-cli | /working-notes |

编辑器与 IDE harness

| Harness | 安装命令 | 调用方式 |
| Cursor | npx -y agent-working-notes install --agent cursor | 自动，或在对话中输入 / |
| GitHub Copilot | npx -y agent-working-notes install --agent copilot | / 菜单、/skills |
| Google Antigravity | npx -y agent-working-notes install --agent antigravity | /working-notes |
| Cline | npx -y agent-working-notes install --agent cline | / 菜单 |
| Kilo Code | npx -y agent-working-notes install --agent kilo | /working-notes |
| Windsurf / Devin Desktop | npx -y agent-working-notes install --agent windsurf | 在 Cascade 中自动生效 |

每个 harness 都读取开放的 Agent Skills 布局。working-notes 还会把托管块写入 CLAUDE.md 和 AGENTS.md，所以只靠指令文件的模式也能拿到这十条规则。

全部 harness，或项目内副本

every supported harness, user scope
npx -y agent-working-notes install --agent all

a project-local copy, committed with the repo
npx -y agent-working-notes install --agent all --scope project

anywhere else that reads SKILL.md
npx -y agent-working-notes install --dir ~/.my-agent/skills

Codex、OpenCode、DeepSeek Harness 和 Antigravity 的项目作用域共用 .agents/skills；安装器只写一份副本，不会每个 harness 各写一份。working-notes list 列出每个解析后的路径，以及是否检测到对应 harness。working-notes doctor 拿已安装的副本和命令行版本做比对。

手动安装

git clone --depth 1 https://github.com/FiredMosquito831/working-notes.git /tmp/working-notes
cp -r /tmp/working-notes ~/.claude/skills/working-notes

把 ~/.claude/skills 换成你的 harness 文档里写的目录。技能需要 SKILL.md 和 templates/；仓库里其余内容都是文档、测试和安装器。

各 harness 的确切路径、验证步骤、更新、卸载和故障排查：docs/INSTALL.md。支持状态和厂商链接：docs/HARNESSES.md。

它会创建什么

/working-notes init 是幂等的，项目进行到一半时运行也安全。它只创建缺失的东西，绝不覆盖你的文件。

your-repo/
├── CLAUDE.md # managed "How we work" block, delimited by markers
├── AGENTS.md # kept byte-identical when the repo already has one
├── WORKING-NOTES.md # the operating manual: rules, repo facts, releases, lessons
├── WORKING-NOTES-ARCHIVE.md # dated diary, superseded blocks, long tables
├── QUEUE.md # the binding PR queue
├── HANDOFF-2026-10-27.md # resume point, newest file is the entry point
└── specs/ # investigations and binding USER DECISIONS blocks

如果你把笔记放在仓库外面，技能就写到仓库旁边，让仓库保持干净。如果笔记放在仓库里面，init 会提议把 .orchestration/ 加进 .gitignore。

什么放在哪里

| 文件 | 用途 | 何时更新 |
| WORKING-NOTES.md | 当前事实：你怎么工作、仓库机制、关卡、产品原则、领域事实、环境、发布历史、经验教训 | 每个 PR 边界和每条经验教训 |
| QUEUE.md | RUNNING / QUEUED / FINISHED / HELD，按约束顺序排列，附证据 | 每个 PR 的开始与结束 |
| HANDOFF-<date>.md | 阅读顺序、确切状态、你欠下什么、先做什么、验证命令 | 每次暂停或上下文压缩 |
| specs/ | 调研、选项、风险、编号问题、决策 | 任何构建之前 |
| CLAUDE.md / AGENTS.md | 入口点，以及十条永不放松的规则 | 一次，之后由 init 刷新 |

子命令

| 命令 | 作用 |
| /working-notes init | 初始化，或补齐缺失内容。可安全重复运行。 |
| /working-notes handoff | 写一个带日期的续接点，以及下次会话要粘贴的段落。 |
| /working-notes queue | 打印运行中、排队中、挂起、已完成，以及你欠下的每个问题。 |
| /working-notes brief <item> | 生成实现者或调研者简报，附上项目的硬性规则。 |
| /working-notes lesson "<text>" | 追加一条带日期和经验来源的教训。 |

无论你是否输入命令，规则都生效。技能只是一次性初始化器，不是运行时依赖。

规则

十条规则，复制进每个项目，由五个首次使用问题调校：

| # | 规则 | 它防止什么 |
| 1 | 先讨论，再构建 | 未达成一致就派活；半生不熟的工作 |
| 2 | 最安全、100% 可用、不破坏任何东西 | 顺手重写，以及「我正好路过」式的回归 |
| 3 | 只扩展，绝不收窄 | 为了适配新情况而悄悄删掉行为 |
| 4 | 一次只开一个生产 PR | 版本冲突和并行智能体混乱 |
| 5 | 每个「已交付」都自己验证 | 相信摘要而不是产物 |
| 6 | 区分 CONFIRMED / UNVERIFIED / NOT DONE | 没有证据的自信断言 |
| 7 | 每个 PR 边界都记录 | 队列与现实脱节 |
| 8 | 绝不碰用户的世界 | 临时运行打到线上服务或真实配置 |
| 9 | 学到就写下教训 | 下个阶段重复同样的错误 |
| 10 | 最终消息就是交付物 | 智能体任务中途失声 |

完整文本，包括委派、验证、CI 和安全规则，见 SKILL.md。

对比

| | 一份很长的 CLAUDE.md | 一套 spec kit | working-notes |
| 智能体先读的规则 | 有 | 部分有 | 有，托管块放在 CLAUDE.md / AGENTS.md |
| 能跨新会话存活的决策 | 没有 | 如果你保留 spec 就有 | 带时间的编号 USER DECISIONS 块 |
| 与现实一致的队列 | 没有 | 没有 | 有约束力的 QUEUE.md，每个 PR 都更新 |
| 并行智能体安全 | 没有 | 没有 | 一个实现者，一次一个生产 PR |
| 「已交付」确实已交付的证据 | 没有 | 没有 | merge/tag/artefact/CI/live 验证配方 |
| 学到的经验如何记录 | 否 | 否 | 带日期、证据和来源的日志 |
| 运行时依赖 | 无 | 一个工具 | 无 |

它不替代智能体自己的规划。它负责智能体无法即兴发挥的部分：决定了什么、下一步是什么、什么算作证据。

适用对象

- 独立开发者：在真实仓库上运行 Claude Code、Cursor、Codex、Copilot、Gemini CLI、OpenCode、Antigravity、Cline、Qwen Code 或 DeepSeek Harness，厌倦了每天早上重新解释项目。
- 团队：希望智能体的工作留下和人类工作一样的痕迹：规格、决策、队列、证据。
- 长周期任务：跨多个上下文窗口的功能开发、迁移、发布列车。
- 任何人：见过智能体什么都没跑就说「完成」。

它刻意带有主张。它假设你想要更少、更安全、证据更充分的变更，宁愿一次性回答五个编号问题，也不愿每个会话重新争论一遍。

FAQ

只适用于 Claude Code 吗？

不是。技能使用开放的 Agent Skills 格式（SKILL.md），Claude Code、Codex、Cursor、GitHub Copilot、Gemini CLI、OpenCode、Antigravity、Cline、Qwen Code、Kilo Code、Windsurf、Command Code 和 DeepSeek Harness 都能读取。安装器还会把受管规则块写入 CLAUDE.md 和 AGENTS.md，所以只靠指令文件的 harness 也能拿到规则。

会覆盖我的 CLAUDE.md 或 AGENTS.md 吗？

不会。它追加一个块，用 和 界定。重新运行 init 只替换这个块。如果 AGENTS.md 存在，两个文件保持一致。

会带来流程开销吗？

五个命名文件加一个规格文件夹。没有额外追踪器，没有仪表盘，运行时不需要命令行。技能是初始化器：文件一旦存在，仓库自己运转。

能在项目中途使用吗？

可以。init 先推导仓库事实（远程、默认分支、版本文件、测试命令、发布工作流、署名），只问它推导不出来的，并用现有标签和文档填充手册。不会覆盖任何东西。

「一个实现者」是什么意思？

只读调查可以和唯一写入者并行运行。生产变更一次只发一个 PR，因为版本文件和发布流程会冲突。这条规则关乎并发安全，与智能体质量无关。

支持 Windows 吗？

支持。命令行是无依赖的 Node，PowerShell 包装脚本处理 Windows 路径，技能的工具规则覆盖 CRLF、PowerShell 和 MSYS 陷阱。

如何更新？
再跑一次安装器，或者执行 npx -y agent-working-notes install --agent all。working-notes doctor 会报告过期的副本。插件用户请执行 /plugin update working-notes。

怎么卸载？

npx -y agent-working-notes uninstall --agent all 会删除本工具安装的副本。项目产物（WORKING-NOTES.md、QUEUE.md、CLAUDE.md 代码块）归你所有，永远不会自动删除。

文档

| 文档 | 内容 |
| 安装 | 每个 harness、确切路径、验证、更新、卸载、故障排查 |
| 工作原理 | 循环、产物、委派协议、验证契约 |
| Harness 矩阵 | 每个 harness 支持什么，技能落在哪里 |
| FAQ | 更详细的回答、限制，以及什么时候不该用它 |
| 发布 | 仓库元数据、发布检查清单、npm 与插件两条路径 |
| 贡献 | 仓库结构、测试、校验、发布流程 |

仓库结构

working-notes/
├── SKILL.md # the skill (canonical text)
├── templates/ # WORKING-NOTES, QUEUE, HANDOFF, SPEC, briefs, verify recipe
├── cli/working-notes.mjs # dependency-free installer
├── install.sh / install.ps1 # platform wrappers
├── .claude-plugin/ # Claude Code plugin and marketplace manifests
├── docs/ # install, method, harness matrix, FAQ
├── assets/ # banner and loop diagram
└── tests/ # installer test suite (node --test)

开发检查

npm test # installer tests
npm run validate # manifests, skill frontmatter, docs coverage, secret scan
claude plugin validate . # Claude Code plugin and marketplace validation

如果它帮你省下了一次重新解释项目的功夫，就给仓库点个 star。这能帮其他跑智能体的人找到它。

Topics: agent skills · Claude Code skill · Codex skill · Cursor skill · GitHub Copilot skill · Gemini CLI skill · OpenCode skill · Antigravity skill · Cline skill · Qwen Code skill · Command Code skills · DeepSeek Harness skills · spec-driven development · multi-agent orchestration · context engineering · AI coding agents · SKILL.md · AGENTS.md · CLAUDE.md · PR queue · handoff notes