Skip to content
BranchesTags

Repository files navigation

Engineering Playbook

面向人类与 AI Coding Agent 的可追溯、可验证工程治理系统。

Machine-verifiable engineering governance for humans and coding agents.

默认路径是 轻量起步：先接入最小治理，按仓库情况再升级。playbook init 支持 --profile（light/standard/strict）控制默认约束强度。

设计依据 / Design Basis

参考大厂（Google、Anthropic、OpenAI、Stripe、Meta、Netflix 等）的 AI Coding Agent / vibe coding 工程实践，抽象为五个支柱：

支柱 机制 解决的问题
小变更单元 Change Record（CHG-XXXX） AI 时代 PR 膨胀、评审不可控
分级护栏 T0–T3 追溯等级 + 风险触发器 + 治理档位 单一门槛必被绕过，风险路径自动升级
机器门禁 playbook check（work/merge 两模式） 把"测试通过"从声明变成机器验证
项目记忆（记忆点） playbook remember / memory list·delete + .playbook/memory/ agent 重复推导已知事实，浪费 token
回档优先（回档点） playbook checkpoint change / rollback（Change 级 tag）+ checkpoint save·restore（未提交工作保护） 恢复成本超过一条命令就是设计缺陷

大厂共识模式全文见 RFC-0002。

3 步用上（推荐）

从本仓库源码安装（发布 tag 后也可用同一方式固定版本）：

python3 -m pip install "git+https://github.com/biuworks/engineering-playbook.git@v0.3.0"
cd /path/to/your-repo
playbook init --profile light  # 新仓库建议优先从 light 起步
playbook doctor

开发者在本仓库内联安装：

python3 -m pip install -e '.[test]'
cd /path/to/your-repo
playbook init --profile light
playbook doctor

然后在目标仓库复制 Skill 与 Agent 入口：

python3 /path/to/engineering-playbook/scripts/adopt-playbook.py .

日常最小闭环：

playbook start --title "Fix checkout bug" --type fix --level auto
# ... 改代码并补测试 ...
playbook check --base origin/main --mode work
playbook finish CHG-0001 --base HEAD

把 Playbook Compliance 配成 Required Status Check（见 Required Status Check）。第一周建议只开：活动 Change + 生产改动测试/豁免。

进阶：T2/T3

需要架构决策、需求追溯、安全/隐私审查时再升级：

playbook init --level T2 --profile strict --language zh-CN
python3 scripts/adopt-playbook.py /path/to/target-repo --level T2 --language zh-CN

等级含义见下方表格；完整流程见 Adoption Guide。

Current Standards

结构拆解（4 个核心块）

  • Engine（执行引擎）：src/playbook/（命令和检查逻辑）
  • Contracts（规则契约）：schemas/ 与 .playbook/policy.yaml（校验边界）
  • Bootstrap（入场脚本）：scripts/ + adoption-manifest.json（决定拷贝哪些文件）
  • Governance 资产（组织规则）：templates/、docs/、skills/（按级别渐进）

只记 4 条命令（最小流程）

  • playbook assess --title "<变更标题>"：先估算这次需求等级
  • playbook start --title "<变更标题>" --type <feature|fix|refactor|docs|ops> --level auto：按估算创建 CR
  • playbook check --base <revision> --mode work：工作态检查
  • playbook finish CHG-0001 --base HEAD：完成闭环并标记 verified

英文版：

  • Assess each requirement first: playbook assess --title "..."
  • Start the change: playbook start --title "..." --type <feature|fix|refactor|docs|ops> --level auto
  • Validate during work: playbook check --base <revision> --mode work
  • Finish the change: playbook finish CHG-0001 --base HEAD

assess 与 start 是动态风险入口（不需要每次 init）：同一仓库里可以连续出现 T1 -> T2 -> T1；--governance-profile 支持 light/standard/strict/quick 进行单次覆盖。

assess and start are designed for dynamic risk: one repo can run T1 -> T2 -> T1 back-to-back. Use --governance-profile for single-run overrides with light/standard/strict/quick.

Templates（中英双套 / Bilingual）

英文模板位于 templates/en-US/，中文模板位于 templates/zh-CN/（17 种 × 2）：文档索引、项目章程、词汇表、路线图、约定、讨论记录、RFC、ADR、需求、追溯矩阵、事故、发布、安全评审、隐私评审、Issue、PR。

Agent Skill Pack（中英双套 / Bilingual）

GitHub Templates

Validation

Run repository checks after changing templates, links, or skills:

python3 scripts/check-playbook.py

安装开发环境并运行机器合规检查：

python3 -m pip install -e '.[test]'
playbook start --title "Add OAuth login" --type feature --level auto
playbook check --base origin/main --mode work

共享策略位于 .playbook/policy.yaml；Policy 与 Change Record 合同分别位于 schemas/policy.schema.json 和 schemas/change.schema.json。

CI 使用 --mode merge，要求活动 Change 达到 verified。仓库管理员还需按 Required Status Check 配置指南 将 Playbook Compliance 设为必需检查。

命令速查 / Command Reference

按职责分层（轻量 / Light → 标准 / Standard → 高强度 / Strict）：

1) 需求管理 / Change Management

  • playbook assess --title "<变更标题>" [--scope path...] [--scan-worktree] [--level auto|T0|T1|T2|T3] [--format text|json]
    • --scan-worktree 可选：将当前未提交改动路径也作为判定输入（默认不扫工作区，避免历史未清问题影响本次评估）
    • playbook assess --title "<change title>" ...
    • 先做本次需求的风险评估，不创建文件。先算等级再决定需要哪些产物。
    • playbook assess --title "..." ...
    • Estimate risk for the upcoming change first, without creating files.
    • playbook start --title "<变更标题>" --type <feature|fix|refactor|docs|ops> [--scope path...] [--scan-worktree] [--level auto|T0|T1|T2|T3] [--light]
    • playbook start --title "..."
    • 自动识别等级并按等级创建 Change Record 与产物（T1 通常最小，T2/T3 自动补齐）。
    • Create the Change Record and required artifacts; --level auto derives from title/scope, with --scan-worktree adding workspace hints.
    • --light：只写 change.yaml，不生成工件模板（省 token；工件检查仍按策略执行，高风险路径不豁免）。
  • playbook check --base <revision> [--mode work|merge]
    • playbook check --base ...
    • 日常工作检查 / merge 前检查（工作场景与合并场景分离）。
    • Daily compliance check / merge gate check.
  • playbook finish CHG-xxxx --base <revision>
    • playbook finish CHG-0001
    • 完成自检并将 Change 标记为 verified。
    • Finish check and mark the change verified.

2) 上下文与安全护栏 / Context & Guardrails

  • playbook context --base <revision> [--format json|yaml] [--brief]
    • playbook context --base HEAD --format json
    • 查看仓库约束上下文、已启动变更、触发风险、记忆点。
    • Show policy context, active changes, trigger risks and memory points.
    • --brief：跳过 changed_paths 与事件日志，记忆只输出名称（省 token 的注入模式）。
    • --brief: skip changed paths and the event log; memory names only (cheap injection mode).
    • playbook status 是 context 的别名（同样含义，便于记忆）。
    • playbook status is an alias of context for short naming.
  • playbook fix --base <revision> [--title ...] [--type ...] [--level auto|T0|T1|T2|T3] [--scope path...] [--scan-worktree]
    • playbook fix --base ...
    • 自动修复常见问题；如缺 Change 会自动启动。
    • Auto-fix common findings; auto-starts missing Change when possible.
  • playbook link CHG-xxxx --adapter <openspec|spec-kit> --path <repo path>
    • playbook link CHG-0001 --adapter openspec --path specs/feature
    • 绑定外部需求/方案到 Change 的追溯字段。
    • Link requirement/design artifacts into the change traceability block.
  • playbook hook session|write|stop
    • playbook hook session / playbook hook write --path src/a.py / playbook hook stop
    • Agent 工具钩子入口，保持 AI 编码时的行为一致性。
    • Tool-neutral agent hook entrypoints.
    • session：会话初始化；write：写前预检；stop：结束前完整检查（更像工具自动化入口，不是手工每次必跑）。
    • session bootstrap context; write pre-write guard; stop end-of-task check. These are primarily for agent/tool automation, not required for every manual workflow.
  • playbook checkpoint save|list|restore
    • playbook checkpoint save --label before-refactor
    • 回滚点（checkpoint）与操作锚点（rollback anchor），保护未提交工作（diff patch 快照）。
    • Rollback anchors for recovery and continuity; snapshots uncommitted work.
  • playbook checkpoint change CHG-xxxx [--message "..."]
    • playbook checkpoint change CHG-0001 --message "before refactor"
    • 给 Change 打提交级回档点（git tag playbook/CHG-xxxx@N），写入 .playbook/checkpoints.json。
    • Create a Change-level rollback point (git tag) recorded in the checkpoints manifest.
  • playbook rollback CHG-xxxx [--tag playbook/CHG-xxxx@N] [--apply]
    • playbook rollback CHG-0001 --tag playbook/CHG-0001@1 --apply
    • 无 --tag 列出回档点；带 --tag 预览影响（diff --stat）；--apply 只恢复该 Change scope 内的文件并把状态重置为 draft（scope 外工作不受影响）。已发布（merged/released/archived）的 Change 拒绝回滚——请创建新的 type fix Change 来发布回滚（镜像 git revert 而非 reset）。
    • List, preview, or apply a Change rollback; restore is scoped to the change and demotes status to draft. Merged/released/archived changes refuse rollback — publish the rollback via a new type fix Change instead (mirrors git revert, not reset).
  • playbook memory show|clear（事件日志 / event log）
    • playbook memory show
    • 项目记忆点（agent 事件日志，用于长流程/多轮协作）读写。
    • Session memory (event log) for long workflows.
  • playbook remember "<事实>" [--type decision|convention|lesson|reference|gotcha]
    • playbook remember "本项目用 uv 管理依赖" --type convention
    • 记录持久记忆点到 .playbook/memory/（frontmatter + 正文，自动维护索引），每次会话的 context/hook session 自动注入；memory list|delete 管理。只记 agent 无法从代码发现的信息（省 token）。
    • Record a durable memory point; injected into agent context each session. memory list|delete manage them. Record only what agents cannot discover from code.

3) 入场脚本 / Entry Scripts (Only These)

  • python3 scripts/adopt-playbook.py <repo> [--level T1|T2|T3] [--language zh-CN|en-US]
    • python3 scripts/adopt-playbook.py .
    • 唯一入场脚本：将最小治理文件引入仓库；按级别渐进加入更多文件。
    • Single bootstrap entry: copies base governance pack into the target repo and incrementally increases scope by level.
  • python3 scripts/check-playbook.py
    • python3 scripts/check-playbook.py
    • 仅校验此 playbook 仓库自身（清单/schema/文档映射）是否完整一致，不做业务仓库合规判断。
    • Only validates playbook repository integrity (manifest/schema/docs map), not project-specific compliance.

Agent 执行入口：

playbook context --base HEAD --format json
playbook context --base HEAD --brief        # 省 token：跳过 changed_paths，记忆只输出名称
playbook fix --base origin/main --title "Add example" --type feature
playbook hook write --path src/example.py
playbook hook write --path src/example.py --severity warn
playbook hook stop --base HEAD
playbook finish CHG-0001 --base HEAD
playbook doctor

playbook checkpoint save --label before-refactor
playbook checkpoint restore CHK-...
playbook checkpoint change CHG-0001 --message "before refactor"   # Change 级回档点
playbook rollback CHG-0001 --tag playbook/CHG-0001@1 --apply      # 回滚（scope 内 + 状态重置 draft）
playbook remember "本项目用 uv 管理依赖" --type convention          # 持久记忆点

生态和并行 Change：

playbook start --title "Change orders" --type feature --scope 'src/orders/**' --scope 'tests/orders/**'
playbook link CHG-0001 --adapter openspec --path openspec/changes/change-orders

Adopt the playbook and skill pack in another repository:

python3 scripts/adopt-playbook.py /path/to/target-repo
python3 scripts/adopt-playbook.py /path/to/target-repo --level T2 --language zh-CN

如果你希望最小化命令入口，只需要记住一条：

python3 scripts/adopt-playbook.py /path/to/target-repo --level T3 --language zh-CN

脚本职责对照 / Script Responsibility Map

  • adopt-playbook.py：入场（一次性拷贝模板与技能文件到目标仓库）
    • adopt-playbook.py: bootstrap entry, copies policy templates and skill files into target repo.
  • check-playbook.py：仓库自检（Playbook 项目本身的结构完整性）
    • check-playbook.py: self-check for repository health and adoption mapping consistency.

为什么要有很多单元测试（即使是文档型项目）

因为约束系统本质是“规则引擎”，不是“文本文档”。主要测试目标是：

  • assess/start/check/finish 在不同等级与命名触发下是否稳定输出一致结果
  • 规则合并（组织策略 + 项目策略）不被破坏
  • 风险触发器、路径匹配、traceability 与 status gate 的边界行为
  • 模板/清单脚本输出的可重复性

Why keep many tests in a docs-first repo:

  • The playbook is a governance policy engine, so bugs are process regressions that directly affect delivery quality.
  • Tests protect the contract between humans/agents and machine checks when rules evolve.
  • As the level model becomes dynamic, many hidden branches appear; tests lock those invariants.

Options

Supported documentation languages: en-US, zh-CN.

默认 --language zh-CN。需要英文优先文档时显式传入 --language en-US。所选语言写入目标仓库的 AGENTS.md 与 docs/project/conventions.md（T2+）。

The adoption scripts copy AGENTS.md and skills/traceable-engineering/ into the target repository. Agents should use skills/traceable-engineering/SKILL.md as the shared workflow entrypoint. AGENTS.md remains the tool-neutral fallback entrypoint for tools that do not auto-discover repository skills.

Recommended Project Adoption

对于大多数仓库，先用 T1（见上方「3 步用上」）。T1 只复制：

AGENTS.md
skills/
  traceable-engineering/
    SKILL.md
.github/
  ISSUE_TEMPLATE/
  PULL_REQUEST_TEMPLATE.md
  workflows/playbook-compliance.yml

For a T2/T3 project, also copy the docs tree:

docs/
  00-index.md
  project/
    charter.md
    glossary.md
    roadmap.md
    conventions.md
  notes/
  rfcs/
  adrs/
  requirements/
    traceability.md
  incidents/
  releases/

For T3 projects, also create:

docs/
  security/
  privacy/

Then decide the traceability level:

Level Use Case Required Artifacts
T0 Temporary scripts or experiments Clear commit messages
T1 Normal projects（默认） Change、verification、tests/exemption
T2 Important projects Notes, RFC, ADR, requirements, traceability matrix
T3 Open source, commercial, security-sensitive, or long-term projects T2 plus security, privacy, release notes, incidents/postmortems

Upgrade the level when a change involves data migration, authentication, authorization, privacy, security, public APIs, protocols, infrastructure, deployment, release, rollback, or incident response.

Adoption Manifest

复制映射及适用等级的机器可读单一事实源是 adoption-manifest.json。scripts/adopt-playbook.py 直接读取该文件；修改 adoption 内容时不要在 README 复制映射规则。

About

No description, website, or topics provided.

Resources

Readme
MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages