scrum-skills

scrum-skills

结构化的敏捷数据 + TDD 纪律 + 开箱就能看的看板，给「和 AI 一起做项目」这件事用。

AI 只负责把需求、任务、实施过程写成结构化 JSON，人打开浏览器就能看到看板、甘特图、里程碑、燃尽图和每个任务的 TDD 追溯链。数据是唯一事实来源，对话记忆不作数。

为什么

• AI 写代码很快，但「做到哪了」全靠人问 → 每个故事/任务的状态、实施日志都落在 agile/ 里，随时可查
• TDD 靠自觉，容易悄悄跳过 → 校验器强制「先有失败的测试，才有实现」：task 过了 red 阶段，日志里必须有一条 fail 记录和一条 pass 记录
• 看板工具要么太重、要么数据锁死 → 三个 JSON 文件 + 一个零依赖 server，数据在你自己仓库里，git diff 就能审

快速开始

# 1. 在任意项目里初始化（生成 AGENTS.md、四个 skill、数据骨架）
npx scrum-skills init .

# 2. 让 AI 读 AGENTS.md，用 scrum-planning 建第一个 story
#    （Claude Code / Cursor / CodeBuddy 等都会读这个文件）

# 3. 校验数据
npx scrum-skills validate

# 4. 打开看板
npx scrum-skills serve        # → http://localhost:4173

init 会建出 agile/ 的三个文件骨架，并把四个 skill 装进 .agents/skills/：

命令

scsk 是 scrum-skills 的等价简写，全局安装后两个命令都可直接用，如 scsk serve。

update 会整篇覆盖框架文件（AGENTS.md、.agents/、tools/validate.mjs）。你在这几个文件里的本地改动不会被偷偷合并，但覆盖前每个文件都会各留一份 <文件>.<yyyyMMdd-HHmmss>.bak，且不会顶掉上一次的备份。 输出里会点名备份文件，并提示用什么话让 agent 合并：直接说「对比 AGENTS.md 与 AGENTS.md.20261026-113045.bak，把我的本地改动合并回来」即可。合并确认无误后再删备份。 只想知道会动哪些文件，加 --dry-run：只报告，不写文件、不建备份。

数据长什么样

agile/ 下只有三个文件：

// 一条故事（节选）
{
  "id": "S-017",
  "type": "bug",                       // feature | bug | debt | spike
  "priority": "P1",                    // P0~P3
  "value": 8,                          // WSJF = value / points
  "bug": {                             // type=bug 时必填三件套
    "severity": "major",
    "environment": "Chrome 120 / Windows 11",
    "steps": "1. 勾选子任务；2. 返回看板；3. 拖动卡片 —— 进度条仍是旧值"
  },
  "acceptance": [
    { "given": "…", "when": "…", "then": "…", "verifyBy": ["S-017-T1"] }
  ],
  "points": 2,
  "status": "ready",
  "sprintId": null,
  "schedule": { "start": "2026-10-20", "end": "2026-10-23" },  // 甘特图的计划条
  "dependsOn": ["S-004"],                                        // 依赖，必须无环
  "blocked": { "reason": "等复现环境确认", "since": "2026-10-22" },
  "scopeChange": { "kind": "added-mid-sprint", "at": "2026-10-15", "reason": "客户临时插需求" },
  "tasks": [
    { "id": "S-017-T1", "title": "写复现缺陷的失败测试", "type": "test", "status": "todo", "files": [] }
  ]
}

迭代 id 形如 R1-S1：R<发布周期>（一个发布周期 = 4 周 = 2 个冲刺）× S<期内冲刺号>；小团队也可以只用 S-01 纯序号，但同一项目不许混用。

看板有什么

内置 AI 助手

看板右下角有个悬浮按钮，点开是右侧抽屉——不用离开看板就能让模型查/改当前项目的敏捷数据。

第一次打开先填参数（存在本机 %APPDATA%/scrum-skills/ai.json，权限 0600，不会写进项目目录）：

Key 不出本机：浏览器只调本机 /api/ai/*，模型请求由 tools/serve.mjs 代为发出，读配置只回 hasKey。

回答长什么样（照官方 chat 模板的版式）：助手正文按 markdown 渲染（标题、列表、表格、行内代码都能显示），工具调用折成一行「更新敏捷数据 · 关键词」可展开看参数与结果，模型的思考过程收成「思考了 N 秒」可折叠块，待审变更是一张能点批准/驳回的卡片。markdown 走 @comark/nuxt（AST → Vue 组件），不用 v-html 拼 HTML。

它手上只有两件工具：

• search_agile：在 agile/backlog|sprints|journal 里按记录检索（S-011 阻塞 这种多关键词要同时命中同一条），命中带出可直接写补丁的路径
• update_agile：按路径打补丁，例如 stories.S-011.status = review；写前跑 tools/validate.mjs，校验不过自动回滚成改前内容

输入框左下角四个图标按钮，从左到右固定这个顺序（加东西在左、策略在最右）：

1. 上传图片：一次最多 4 张，输入框里按 Ctrl+V 也能粘贴截图。图片先在本地缩到长边 1400 再按 JPEG 编码，以缩略图挂在输入框上方（可逐张删除），发送后随文字按 OpenAI 多模态格式（image_url）带给模型。历史里只带最近 4 张图，更早的换成一句「图片已省略」占位；服务端按每张 800 token 计入上下文预算。模型本身不支持图片时（例如 DeepSeek 的 chat / reasoner），报错会直接提示换成支持视觉模型的接口。
2. 新建会话（+ 图标）：先把当前这一轮完整存进本地历史，再清空对话区回到欢迎页
3. 历史会话：弹出列表，每条给出标题（第一条提问的开头）、相对时间与消息条数，点一条即可切回去接着问；当前那条有底色
4. 审核策略（盾牌 / 闪电图标，点一下弹下拉，当前项打勾）：手动审核（默认）改文件前先出「待审变更」卡，逐条列出路径与改前改后值，点批准才写入，驳回则文件不动；自动审核直接写入 + 立即校验，失败回滚

会话只存在这台浏览器（localStorage 的 scrum-skills:ai:threads:v1，最多保留 20 个，超了丢最老的），服务端一概不知。图片不落盘——一张截图 base64 就有上百 KB，存几个会话就会把 localStorage 撑爆，所以落盘前清空图片 url；恢复后原位显示「图片未保存」占位，这类空图也不会被拼进下一次请求。抽屉每次打开时按主题存的那条会话自动恢复。抽屉是整屏覆盖的，打开期间会锁住背后主页的纵向滚动，关掉即恢复。

工具永远跟着「看板当前打开的项目」走，换项目不会串。

纯静态托管（只放 assets/board）时没有 /api/ai/*，此时对话不可用；pnpm serve 才带这套能力。

校验器管什么

validate 是这套体系的地基，错误会让它退出码非 0：

• 引用完整性双向一致：epic.stories ↔ story.epicId、sprint.stories ↔ story.sprintId、journal.taskId ↔ task
• 状态机：story draft → ready → in-progress → review → done（不做就走 cancelled 终态），task todo → red → green → refactored → done（只能前进）
• TDD 铁律：task 到 green 之后，日志必须首条 fail、后有 pass；done 时末条必须是 pass
• story 到 done：所有 task 必须 done，且不许仍标着 blocked
• 已取消（cancelled）：不要求验收标准、也不要求 task 全部 done；但还挂着 blocked 会报错，仍留在迭代里给 WARN —— 且它的点数不计入承诺容量、燃尽图与里程碑完成度，免得「不做了」把进度拖成永远完不成
• 依赖：dependsOn 必须存在、不能自依赖、不能成环（DFS 检测）
• 需求属性：type / priority / value 合法；type: bug 必须有 severity + environment + steps
• 验收标准的 verifyBy 必须指向同一 story 的 task
• 迭代 id 格式与序号连续、同时只能有一个活跃迭代
• 里程碑 reached 时挂的故事必须全部完成

给 WARN 的（不阻塞）：验收没绑验证任务、史诗缺 keyResults、计划区间超出迭代、承诺点数超容量、被阻塞的故事仍排在迭代里等。

本地开发

pnpm dev                       # Nuxt dev（HMR），读仓库根的 agile/（/api/ai 走 server/middleware）
AGILE_DIR=/别的项目 pnpm dev     # 看别的项目的数据

pnpm build                     # 构建看板静态产物 → assets/board
pnpm validate                  # 只校验数据
pnpm test                      # 回归测试（校验器 / 看板皮肤与泳道 / 卡片操作 / 项目目录 / AI 服务与面板，106 个用例）
pnpm serve                     # 起看板（读目标目录的 agile/，同时提供 /api/ai）

看板源码在 apps/board/（Nuxt 4 + Nuxt UI，纯静态产物，无服务端、无外部字体/图标请求）。assets/board/ 是构建产物，不进 git，发布前由 prepublishOnly 自动重建。

License

MIT