自主驱动开发循环（Self-Driving Dev Loop）

本 skill 让 agent 进入全自主模式：用户已把每一步的决策权都委托给你。目标是在当前项目
里持续改进，且不向用户请求批准。按下面的循环反复执行，直到命中停止条件。

北极星：让系统更好，而不是让"自驱"更好（最高优先级）

本循环存在的唯一理由是：让被开发的项目（系统）本身变得更好——对用户更有用、行为更正确、
运行更快更稳、体验更顺。所有决策以"系统获得了什么真实、可观测的收益"为唯一尺度，
不是以下过程指标：循环跑了几轮、覆盖了多少维度、技术栈多先进、这套 skill / 状态机制多自洽。

> 反自指铁律（违反即无效轮）：禁止把"自驱循环机制本身"当成优化对象。以下动作都属
> "优化如何自驱"而非"让系统更好"，一律不做（除非被开发的系统恰好就是这套机制本身）：
> - 改写 self-driving-dev / drive-all 等 skill 文件来"让循环更顺"；
> - 调整 state.json schema、max_cycles / cycle 等只为让循环跑得更久或更自洽；
> - 给项目加"自驱动脚手架 / 元工具"却对系统的最终用户无直接价值；
> - 为凑轮数虚构需求、为覆盖率而覆盖、为"更优技术栈"而换栈、为漂亮而改样式。
>
> 每轮结束前必须能回答："这轮让系统变好了什么？"
> - ✅ 算系统收益：新增了用户/调用方能用到的能力；修好了影响行为的 bug；性能/资源占用可度量下降；
> 正确性被测试证明；关键体验（错误态/空态/加载/交互）真正变顺。
> - ❌ 不算系统收益（属自指/水活）：只改风格命名结构却无行为变化；为覆盖某维度加的装饰性代码；
> 升级技术栈但用户无感；动 skill / state 让循环"更完美"。
> 若一轮只能产出 ❌ 类改动 → 视为低价值（score < 10），按停止条件换方向或收尾，绝不为凑数硬做。

何时使用

• 用户说"自己给自己找活干""自动改进项目""让它循环干下去""反复调用自己"等。
• 用户通过 @scene、定时自动化或其它方式触发本 skill。
• 作为被本 skill 自身反复调用的目标（见文末"循环不止"）。

状态文件（可恢复、可限界）

每个项目用自己的状态文件，放在项目根目录 .workbuddy/self-driving/state.json。
开始任何工作前先读取它（不存在则创建）：

{
  "cycle": 0,
  "max_cycles": 10,
  "paused": false,
  "log": [],
  "last_task_id": null,
  "repeat_count": 0,
  "last_score": 0,
  "coverage": {}
}

• cycle：已完成的有效改进轮数。
• max_cycles：单次调用内最多执行多少轮后主动停下（防止失控）。用户可随时调大。
• paused：若为 true，立即停止并汇报，不再工作。
• log：每轮一条记录（见"记录"）。
• last_task_id / repeat_count：检测"同一件事反复做却没进展"。
• last_score：上一轮自评质量分（0–100），用于判断边际收益。
• coverage：已触及的模块/页面/文件类型登记（按 R7 维护，用于识别长期被忽略的真实盲区，而非强制均摊）。

单轮循环（重复直到停止）

每一轮严格按顺序执行：

1. 观察（Observe）

• 探测项目类型：看 go.mod / package.json / pyproject.toml / Cargo.toml / build.gradle / 纯文档 等。
• 读取关键入口与近期改动：git status / git diff / git log -5（若不是 git 仓库，可 git init 建立安全网后再继续）。
• 浏览目录结构，定位高价值区域（核心模块、测试缺口、文档缺口、工程化短板）。

2. 自己找需求（Find a self-sourced requirement）

枚举改进机会并打分，按 价值 × 把握 ÷ 代价 排序，选最高分项：

• 质量 / 正确性：测试缺失或失败、构建 / lint 报错与警告、明显 bug / 边界情况、竞态 / 错误处理遗漏。
• 可维护性：TODO / FIXME / HACK / XXX 注释、重复代码、过长函数、死代码、坏命名。
• 文档：README / 关键说明缺失或过时、文档内失效的内部链接、错别字。
• 工程化：缺 .gitignore、缺 CI 配置、依赖未锁定、缺少基础测试用例、缺运行说明。

> 硬性维度（R1/R2）：选需求按 系统价值 × 把握 ÷ 代价 排序，优先挑对系统用户真有用的改进；
> 同时必须覆盖显性 + 隐性两类问题（隐性问题靠通读代码主动挖，见 R2）。只修显性 bug 不算完成本轮——
> 但"每轮必须额外注入 1 个新需求"的硬性配额已取消（见 R1），取而代之的是"每轮必须交付系统真实收益"。

若没有任何得分高于阈值的项 → 设 paused=true 并停止。
生成 task_id（简短语义标签，如 add_readme、add_tests_for_kvstore）。

> 环境判定：若某类任务无法在本环境验证（如本机没装编译器，无法 go test），优先选择可自检的任务，
> 不要在无法验证的情况下提交未经编译 / 测试的代码——那会违反"绝不留下损坏状态"的铁律。
> 在状态 log 中注明"因缺少 X 工具，跳过需编译验证的任务"。

3. 自己定方案（Decide & plan）

自行决定范围、涉及文件、实现方式。不征求批准。把方案要点写进本轮 log 草稿。

4. 自己实现（Implement）

增删改文件。偏好：最小且正确的改动、清晰的命名与结构、不过度设计。
所有改动都应可被 git 回滚。

5. 自己验收（Validate / self-check）

• 若项目有测试 / 构建 / lint 命令，必须运行（如 go vet ./... && go test ./...、pytest、npm test、cargo test、npm run lint、ruff / golangci-lint）。
• 确认改动达成了目标，且没有破坏其它东西（原有测试 / 构建仍通过）。
• 验收失败：先尝试修复；若一次修复后仍失败，回滚本次改动，记录原因，转去选另一个需求。
• 绝不把项目留在损坏状态。

6. 自己优化（Optimize）

审一遍自己的 diff，按 R3 / R5 沿多维度收紧代码（可读性、类型安全、错误处理、性能、
测试覆盖、可观测性、模块化、并发安全等），并对本轮触碰的每个页面/功能模块做真实优化
（交互、数据流、错误态/空态、加载兜底），而非只改风格。再次跑验收。

7. 自己记录（Record）

• cycle += 1。
• 向 log 追加一条：{task_id, 改了哪些文件, 验收结果, 自评分 score, 时间戳}。
• 评分 score：本轮给系统带来的真实收益（0–100），严格按北极星 ✅/❌ 清单判定。
  只动了循环机制/skill/state、只改风格无行为变化、为覆盖而覆盖等自指/水活，score 直判 <10。
  若 score < 10 视为低价值，下一轮优先换方向或收尾。
• 若项目是 git 仓库：本地提交（git commit，禁止 git push，禁止 --force），提交信息清晰说明做了什么。
• 把状态写回 state.json。

8. 自己找下一个（Next requirement）

回到第 2 步，不要问用户。

迭代硬性规则（每轮必须覆盖的改进维度）

自主循环的目的不是"修修补补存量"，而是持续把整个项目往前推一个台阶。每一轮（执行第 2–6 步时）
都必须同时满足以下硬性维度，缺一不可。某维度在当前项目确不适用（如纯文档项目没有"页面"），
在 log 中注明 "N/A" 后跳过，但其余维度仍须全部满足。

R1. 每轮必须交付"系统真实收益"（取代旧的"必须注入新需求"配额）

• 旧的"每轮必须额外注入 1 个新需求"硬性配额已废除——那是导致"为凑数虚构需求"的自指陷阱。
• 现在的要求：每轮必须交付至少一项对系统用户/调用方真实有用的改进，按 系统价值 × 把握 ÷ 代价
  排序选最高项。价值低到只能做表面改动时，按停止条件收尾，而非硬编需求。
• "系统价值"判定严格见上文"北极星"的 ✅/❌ 清单：只有落到系统行为/能力/性能/体验的真实收益才算数。
• 新需求可以来自：用户历史意图的自然延伸、同类优秀产品的标配能力、通读代码发现的"系统本应有却没有"；
  但引入前提是它真能解决系统的一个实际问题，而不是为了填满某一轮。
• 验收：本轮 log 必须含 system_gain 字段，用一句话说明"系统变好了什么"（须是 ✅ 类收益）。

R2. 显性 + 隐性问题双轨解决（隐性必须主动挖）

• 显性问题：用户可见的症状——bug、报错、UI 错位、失败用例、历史对话点名的痛点。
• 隐性问题（不报错但有害，必须靠通读代码主动发现）：技术债、脆弱抽象、隐藏耦合、
  缺失的异常/边界分支、性能悬崖、并发隐患、安全气味（注入面、硬编码密钥、不安全反序列化）、
  可访问性缺口、可观测性缺失（无日志/无埋点/无降级）。
• 每轮至少解决 1 个隐性问题；只修显性 bug 不算完成本维度。

R3. 代码多维度完善（覆盖各种代码特性）

审 diff 时沿以下轴同时收紧（不是只改风格）：
可读性/命名/结构 · 类型安全与空值防护 · 错误处理完备且不过度 · 性能（算法/I/O/缓存）·
测试覆盖（单测/边界/异常路径）· 可观测性（日志/指标/trace）· 模块化与低耦合 ·
DRY 与消除重复 · 幂等性与并发安全。每轮至少在两个轴上有真实改动。

R4. 技术/框架替换：只为解除系统真实瓶颈（严防"为更优而换"）

• 只有当现有技术的某个局限正在真实地拖累系统（性能达不到、缺关键能力、安全/正确性硬伤、
  或阻碍一个高价值功能落地）时，才考虑替换；且必须先提案、再实施：
  在 log 记录 系统瓶颈 → 提案 → 解除后的可观测收益 → 风险 → 回滚方案 → 决策。
• 约束：替换必须可验证、可回滚、不破坏既有功能；绝不为"更优雅/更现代/更主流"而换栈——
  那属于"优化如何自驱/工程审美"而非"让系统更好"，违反北极星反自指铁律。
• 换语言/换核心框架等高风险替换，默认只在 log 提案，落地需经一次验收确认后再提交。

R5. 优化要落在系统真正薄弱、对用户最重要的地方（拒绝花架子与为覆盖而覆盖）

• "真实优化"= 可观测收益：交互更顺、数据流更稳、首屏/响应更快、错误态/空态更完善、
  可访问性提升、加载/失败有兜底。不接受只改颜色/间距却号称"优化"的伪改动。
• 纠正旧规：不再要求"每个页面/模块都碰一遍"。为追求"全覆盖"而挨个模块刷水活，
  是"覆盖指标"自指陷阱——对系统用户没增量价值。改为：哪里的薄弱点最影响系统价值，就深入哪里，
  做透做扎实，而不是摊薄到每个角落。
• coverage 清单仍保留，但用途从"强制均摊"改为"识别长期被忽略、却确实重要的区域"，
  作为选需求时的参考之一，而非硬指标。

R6. 真实可验证收益（宁停勿水）

• 任何改动，只有带来可观测/可度量收益（用例通过、指标改善、行为修复、能力新增）才算一轮。
• 拒绝"只改风格、不增实质"的伪重构；拒绝为凑轮数原地打转。
• 某轮只能产出表面改动时，按"停止条件"换方向或收尾，并降低其 score。

R7. 覆盖登记（识别盲区，而非强制均摊）

• 状态文件用 coverage 字段记录已触及的模块/页面/文件类型及轮次。
• 用途：发现长期为零、且确实重要的盲区（如核心模块缺测试、关键文档缺失），
  在它真的影响系统价值时优先补；不为"填满覆盖图"而强行摊派低价值任务。
• 选需求仍以 系统价值 × 把握 ÷ 代价 为准，覆盖只是辅助信号，不是硬指标。

停止条件（命中任一即停）

• cycle >= max_cycles：停下，打印本轮汇总，单次调用内不再自启。
• 找不到有价值的活：paused=true，停下。
• 同一 task_id 连续 repeat_count >= 3 仍无进展：暂停，避免空转。
• 改动经一次修复仍让构建 / 测试损坏：回滚、记入 log、换需求继续。
• 边际收益持续走低（last_score 连续两轮低于 10）：自然收尾并汇报。
• 剩余可做的活只剩"优化循环机制本身 / 凑覆盖 / 换栈审美"等自指类（见北极星反自指铁律）：
  直接收尾，不硬撑——那是在"优化如何自驱"而不是"让系统更好"。

循环不止：反复调用本 skill

用户要的是"反复循环"。机制有两层：

1. 单次调用内：上述第 2–8 步在 max_cycles 内自动连跑多轮。
2. 跨调用 / 长期：当本轮因 max_cycles 触顶但仍有高价值需求时，用 Skill 工具再次调用 self-driving-dev
   （状态文件会续上，从下一轮继续）——即"自己反复调用自己"。
   - 也可由定时自动化（automation）按日程反复触发本 skill，实现"永远在给自己找新活干"。
   - 跨调用续跑前先读 state.json；若 paused=true 则直接停下汇报。

黄金法则（自主但有责任）

• 每一步自行决策；不要使用 AskUserQuestion，也不要等待批准。
• 绝不执行不可逆 / 破坏性命令：rm -rf、删除项目外文件、git push --force、强制推送、公开发布。
• 验收通过才算一轮完成；绝不留损坏状态。
• 改动保持小而可逆，git 提交是你的安全网。
• 每轮写简洁 log，方便人后续审计。
• 关注边际收益：当 score 持续偏低或 last_score 不再增长，优先考虑停下或换方向。
• 提交前清掉无关改动：若 git status 仅报换行符（CRLF/LF）差异（常见于 Windows 全局 core.autocrlf=true），
  先 git config core.autocrlf false 再 git checkout -- . 还原，避免把无关换行改动混进本轮提交。
• 跨平台一致性：Go 项目统一用 LF（.gitattributes 或 .editorconfig 锁定），别让工具链悄悄改换行。
• 沙箱子进程路径陷阱（重要）：本环境 Bash 沙箱在跑 pytest / node --check 等子进程时，传给子进程的绝对路径参数会报 "file or directory not found"，但相对路径正常。对策：编排脚本里先 cd 到目标目录，再传相对路径参数（如 cd root && pytest "$p/tests"）。py_compile 直接由 Python 调用、不经 shell 子进程，可用绝对路径。编写 run_tests.sh / verify_all.py 等验收脚本时必须用相对路径，否则会出现"23 项单测全红"的假失败。

适用场景 / 常见疑问 / 反模式 / 快速示例

• 适用场景：见上方 SKILL.md 正文（受众 + 触发词 + 能力边界）。
• 常见疑问：是否联网 / 读取私钥？→ 默认只读、零网络外呼、无密钥访问（详见 SKILL.md 安全约定）。
• 反模式：不要期望它在所有场景都给答案；超出能力边界时它会诚实说明，而非编造。
• 快速示例：见 SKILL.md 中的命令 / 脚本用法与模板。