SuperAPI AI 工具集

backlog-charter

编程与开发

查看项目

更新于 10-16 12:15

技能介绍

用途

backlog-charter 用于为项目建立并维护一个持久的参考基准。核心产物是放在目标仓库根目录、与 README.md 同级的 CHARTER.md,它记录“什么是好的状态”:问题、方法、明确的非目标、可验证目标,以及供 backlog 衡量的不可变决策历史。其他技能在该文件缺失时可优雅降级,因此是否采用此文件由项目自行选择。

该文件回答的是“什么是好的状态/为什么”,与 _context.md(操作性事实、HOW 知识)、CLAUDE.md(仓库内工作约定)、README.md(对外介绍)区分开。运营性知识不属于 CHARTER.md。

主要能力与三层结构

CHARTER.md 分为三层,各有不同的修改纪律:

  • 第 1 层 · 方向:Problem、Approach、Non-Goals。人工把关:提出 → 确认 → 应用。移动最慢,是范围收缩后仍保留的核心。
  • 第 2 层 · 谓词:Objectives。状态推进(active → validated/deferred)需要证据;增删目标需人工把关。
  • 第 3 层 · 历史:Decisions。只追加,绝不编辑或删除某行;反转通过新的 supersedes 行进行。来源不可变。

这种分层用于防止基准自我演化成橡皮图章:方向变更受门控,目标状态需要证据,历史被冻结。

使用方式

技能依据文件状态路由,可重复运行:

  • 创建模式:当仓库根不存在 CHARTER.md,或以 backlog-charter create 调用且无该文件时使用。从仓库信号起草:README.md ≻ CLAUDE.md ≻ 开放的 epic/issue ≻ 最近提交 ≻ CHANGELOG.md;信号冲突时在访谈中呈现冲突而非静默取舍。通过访谈补充并锐化 Problem、Approach、Non-Goals 和初始 Objectives,然后按模板写入仓库根 CHARTER.md,revision 为 1,last_amended 为当天。
  • 修订模式:当仓库根已存在 CHARTER.md,或以 backlog-charter amend 调用时使用。先重读当前文件,按三层纪律应用变更;可接受 backlog-triage 的 Alignment Check 报告作为提案种子。应用被接受的修订后,将 last_amended 更新为当天并递增 revision,然后运行 node skills/backlog-charter/scripts/check-size.js 确认仍满足 5 分钟阅读量;若脚本警告,则压缩过长的 deferred 列表或过大的 Decisions 理由。
  • grill 模式:用于编写 spec/capabilities.md(CHARTER.md 与当前 sprint 之间的中间层)。调用方式为 backlog-charter grill(全新)或 backlog-charter grill <capability-slug>(重跑,只打磨指定能力)。在已有代码但无 spec/capabilities.md 的项目上,先运行 node skills/backlog-charter/scripts/extract-signals.js --json 获取原始能力信号草稿作为访谈种子;脚本不会自行写入文件。

目标与能力约定

目标应表述为可验证谓词而非任务;允许混合严格度(可运行检查为理想,可观察陈述可接受);使用 O<n> ID 追踪;已删除目标的 ID 不得复用;记录来源 src(user、inferred 或 execution)。

能力准入需满足多数条件:是重复出现的决策边界而非目录名;拥有主要 relay-learning 归属;Goal 可表述为可观察的用户或运营结果;其 Behavior 与 Hard Constraint 与相邻候选有实质差异。两名候选若谓词几乎相同则合并;若一个候选需要超过五个 Behavior 才完整,则按其描述的契约边界拆分。建议目标为 5–10 个能力,超过 12 个能力或 400 行时告警,仅在超过 500 行、超过 15 个能力或所有权边界要求分离审查时才拆分。

每个能力按以下顺序访谈:Goal(一句话,可观察结果)→ In-scope / Out-of-scope → Expected Behaviors(三条可验证谓词)→ Hard Constraints(两条不越的红线)。第一遍每个能力止于三条 Behavior 与两条 Hard Constraint。

3 轴谓词测试

每条 Behavior 与 Hard Constraint 提交前须通过三个轴:

  • Authority 轴:若代理可测量地满足但忽略用户意图,用户是否会不满?是则谓词欠明确,需细化或提升为 Hard Constraint。
  • Distributional 轴:该谓词在未见代码区域或未见负载下是否成立?否则改写为环境无关,或限定其成立条件。
  • Manipulability 轴:代理能否通过修改测量通道而非系统本身来满足?能则该谓词可被博弈,需在规范之外增加结构性限制。

未能通过任一轴的谓词应重写或拆分。

适用场景与限制

适用于需要为 backlog、冲刺计划与漂移检测建立稳定衡量基准的软件项目,尤其适合希望方向变更受门控、目标状态需证据、决策历史不可变的团队。

限制与边界:具体安装命令、支持的运行环境、是否收费及价格、平台信息均暂未提供。创建模式中,Decisions 表可留空;仅当既有设计文档、ADR 或重要已合并 PR 已记录方向时,才预置 3–5 行,并注意从 revision 2 起其内容即不可变。grill 模式不编辑 Learnings 与 Decisions 区(Learnings 由受限的 append-learnings 写入器在标记之间追加)。spec/capabilities.md 变更后不递增 revision,以 git blame 为准。references/capabilities.md 目前为占位内容。