ac-sync Skill 技能

ac-sync 是一个专为 Claude Code 等 AI Coding 工具设计的开发状态同步 Skill，通过维护一个标准化的状态文档（docs/STATE.md），让 AI Agent 在跨会话工作时能够记住项目的当前进度、待办事项、技术债和历史决策，解决「休假回来想不起开发到哪了」或「被紧急需求打断后技术债慢慢被遗忘」的常见痛点。

核心能力

标准化状态文档模型：ac-sync 定义了一套六节结构的状态文档模板（GOAL / NOW / NEXT / DEBT / LOG / MAP），每节有明确的用途和行数上限。GOAL 记录大方向一句话，NOW 记录当前在干什么及卡点，NEXT 列出带验收标准的任务列表，DEBT 记录技术债及触发修复的条件，LOG 记录历史变更及决策理由，MAP 作为相关文档路径的路由表。

语义感知的同步流程：执行同步时，Agent 会主动问两个关键问题——这次工作碰了哪些文档描述的东西（经 MAP 反查文档耦合）？以及这次工作是否触发了某条技术债的「什么情况该修」条件？这种机制确保状态文件不只是机械记录，还能主动发现被遗忘的技术债和文档脱节问题。

生命周期管理（完成即删）：状态条目的流转遵循严格规则——DEBT → 决定修复 → NEXT → 修复完成 → LOG 记一行原因 → 原条目删除。完成的任务不留 ✅ 标记，占用热区空间，历史完全保留在 LOG 中，git 历史里随时可查。

行数上限门控（hook 兜底）：每节有明确的行数上限（NOW ≤10 / NEXT ≤15 / DEBT ≤15 / LOG ≤12 / MAP ≤8 / GOAL ≤3），配合一个 check.py 脚本挂在 Claude Code 的 Stop Hook 上。当状态文件行数超限时，Stop 被 exit 2 拦下，Agent 必须先压缩各节行数才能继续工作，从机制上而非自觉性上保证状态文件不会膨胀成垃圾堆。

提交边界触发：推荐在每次 git commit 前执行同步，状态文档的变更和代码改动进入同一个 commit，保证文档和代码版本一一对应，日后回溯时状态和代码必然同步。

安装配置

前置条件：需要一个已配置好的 Claude Code 环境，以及目标项目基于 Git 管理。

基础安装（Skill 模式）：在目标项目目录下执行 install.sh 即可将 ac-sync 安装为该项目的 Skill，Skill 会被加载进 Claude Code 的工具链。之后在 Claude Code 对话中直接说「ac-sync」或「同步状态」即可触发同步流程。

双 Hook 安装（推荐生产用法）：执行 install.sh --hook 可同时安装 Skill 和双 Hook——Stop Hook 负责行数门控，SessionStart Hook 负责每次会话开始时自动打印一行「开工先读 STATE.md」的提示，确保 Agent 从会话第一句话开始就知道查状态文件。

其他安装选项：install.sh --unhook 卸载 Hook，install.sh --check 检查 check.py 是否与项目目录同步。

使用步骤

新建状态文件（新项目）：Agent 通过读取 git log 和 README 了解项目背景，按模板生成初始的 STATE.md，写入 GOAL（若有）和基础结构，然后确保 CLAUDE.md 中有一行指向状态文件的「门牌」，保证后续会话能找到。

感知与判断（同步入口）：每次触发 ac-sync 时，Agent 先从本次工作内容、git log 和测试结果感知发生了什么变化，再判断是否存在完成未删条目、新债未记录、NOW 位置过时、债到期未升 NEXT 等偏差。

文档耦合检查：针对 MAP 节中记录的文档路径，反查本次工作是否触碰了某些文档描述的内容。如果碰了且有变更，需要决定是当场更新文档还是立一个新的 NEXT 任务来处理文档更新。

卫生检查（每次必做）：用 check.py caps 命令检查各节行数是否超限（不靠目测），检查热区是否有 ✅ 墓碑块、时间戳叙事或详情堆积，检查 MAP 节路径是否断链，检查环境门牌（CLAUDE.md 指针）和坟场（archive/ 目录）是否存在。

报告与收尾：同步完成后按模板输出五段式报告——[感知] 这次做了什么，[偏差] 偏差项（无则写无），[卫生] 各节实际行数，[环境] 四项环境检查结果（各一词），[行动] 实际修改了什么，[待决策] 本次未解决需人定的决策事项（如有则物化进 NEXT 或 DEBT）。

适用场景

多人协作项目的上下文传承：开发者 A 休假前同步状态，开发者 B 回来读 STATE.md 即可了解项目当前进展，无需额外口头交接。

长时间项目维护：项目经历数月开发后，新接手者或同一开发者在长间隙后回来，通过读 STATE.md 即可快速重建项目当前状态，而非翻 git log 靠猜。

技术债管理：DEBT 节让技术债不再只活在「当时都知道」里——每次收工同步会主动反查本次工作是否触发了某条债的到期条件，等真要做某功能时债是被翻出来的，不是被想起来的。

Agent Loop 自运转：作者实际使用中发现，可以让 Agent 自己读 state 文档、自己挑当前最该做的任务、自己实现、再更新 state，然后继续挑下一个——浅浅跑起了一个自主运转的开发 Loop，大幅降低日常维护的认知成本。

适用人群

高频使用 Claude Code 进行项目开发的程序员，尤其是同时维护多个项目、经常被紧急需求打断、或者团队内需要交接项目上下文的开发者；对于个人开发者，这个 Skill 解决了「休假回来想不起开发到哪了」的经典困境；对于团队开发者，状态文件成为团队共享的项目记忆，不依赖个人脑记。

工作原理

ac-sync 本质上是一套约定和一套工具脚本的组合。约定定义了状态文档的六节结构、每节的数据约束（行数上限、完成即删原则、LOG 记 why 而非 what），以及同步流程的五个步骤。工具脚本 check.py 负责在 Stop Hook 阶段检查行数是否合规，install.sh 负责将 Skill、Stop Hook 和 SessionStart Hook 安装到目标项目。当 Agent 在项目上下文中被调用时，按照约定对状态文件进行读取、同步和更新操作。

官方链接

https://github.com/qkyufw/ac-sync