Skip to content

USAGE.zh.md

Latest commit

 

History

History
286 lines (197 loc) · 7.16 KB

USAGE.zh.md

File metadata and controls

286 lines (197 loc) · 7.16 KB
Raw

使用 PACT

PACT 是一层面向 AI 辅助软件开发的协议，不替代编辑器、agent、测试、git、部署流水线或产品判断。

它的作用是让功能开发保持显式：

意图 -> 契约 -> 实现 -> 验证 -> 发布归档

English: USAGE.md

1. 选择适配方式

PACT 的协议层不绑定具体工具，但不同 AI 工具读取项目规则的方式不同。

工具 推荐适配方式 支持程度
Claude Code .claude/commands/*.md slash commands 一等支持
Codex AGENTS.md + .pact/ 脚本和模板 兼容
Cursor .cursor/rules/pact.mdc + .pact/ 脚本和模板 兼容

详细说明：

2. 安装到项目

详细安装选项：INSTALL.zh.md

推荐使用远程安装器：

curl -fsSL https://raw.githubusercontent.com/Hypho/pact/main/scripts/install-from-github.sh | bash -s -- --target . --mode auto

Windows PowerShell：

powershell -ExecutionPolicy Bypass -Command "irm https://raw.githubusercontent.com/Hypho/pact/main/scripts/install-from-github.ps1 | iex"

这种方式会直接把 PACT 文件安装到目标项目目录。

如果你正在使用 PACT 源码仓库，也可以在仓库根目录执行复制命令：

cp -r CLAUDE.md .claude .pact AGENTS.md .cursor your-project/

或使用安装脚本：

bash scripts/install-pact.sh --target your-project --mode auto

Windows PowerShell：

.\scripts\install-pact.ps1 -Target your-project -Mode auto

如果你在包含 pact/ 克隆目录的父目录中复制，需要给源路径加上 pact/ 前缀：

cp -r pact/CLAUDE.md pact/.claude pact/.pact pact/AGENTS.md pact/.cursor your-project/

根据工具选择对应文件集合。

最小通用集合

.pact/
AGENTS.md

Claude Code 一等支持集合

CLAUDE.md
.claude/commands/
.pact/

Codex 集合

AGENTS.md
.pact/

Cursor 集合

.cursor/rules/pact.mdc
.pact/
AGENTS.md

AGENTS.md 是跨工具 agent 入口。CLAUDE.md 只服务 Claude Code。若某个模块有强局部约定，可从 .pact/templates/module-AGENTS.md 创建模块级 AGENTS.md。

3. 初始化项目

在 Claude Code 中：

/pact.init
/pact.scope

在 Codex 或 Cursor 中，用自然语言要求 agent 执行相同阶段：

请按 PACT 初始化当前项目，创建或更新 constitution、PAD 和 state。
然后在第一个功能开始前执行 PACT scope 适用性评估。

结果：

  • /pact.init 建立项目级事实：constitution、Product Spine / PAD 初稿、state。
  • /pact.scope 判断 PACT 是否适合当前项目，并识别风险边界。
  • scope 建议在第一个功能前执行，但它不是状态机阶段。
  • 在正式功能开发前，建议补齐 PAD 中的产品目标、核心业务主流程、功能类型定义、核心实体和体验一致性规则。

4. 开发一个功能

一个功能按主流程推进：

/pact.pid
/pact.contract
/pact.build
/pact.verify
/pact.ship

如果工具不支持 slash commands，使用自然语言等价指令：

为 [功能名] 创建 PACT PID Card。
根据 PID Card 生成行为契约。
按契约实现功能。
用真实命令输出验证功能。
PASS 后发布归档该功能。

预期产物：

阶段 产物
pid .pact/specs/[功能名]-pid.md
contract .pact/contracts/[功能名].md
build 代码变更 + state.md 进入 build-complete
verify .pact/knowledge/[功能名]-verify.md
ship 归档 contract + 更新 state

Global Spine Lite 在不增加日常流程步骤的前提下增加两个全局锚点：

主干 文件 作用
Product Spine .pact/specs/PAD.md 产品目标、核心业务主流程、实体、状态、体验一致性、功能类型
Architecture Spine .pact/core/architecture.md 模块边界、实体归属、状态机归属、权限判断位置、依赖方向、ADR 触发条件

执行 /pact.pid 时，功能应映射到 PAD 的业务主流程 Step，或标记为辅助 / 管理 / 实验并说明理由。执行 /pact.build 时，对照相关 architecture 边界检查实现。

5. 什么时候暂停

PACT 在以下情况应该暂停，而不是继续猜：

  • 命中高风险边界
  • 缺少 PID Card、contract 或 verify 记录
  • contract lint 或 verify lint 失败
  • verify 为 FAIL 或 INCONCLUSIVE
  • 需要人工验收
  • 大功能需要执行计划

暂停是决策点，不是要绕过的错误。

6. 日常维护

每完成 3-5 个功能，执行：

/pact.retro

在 Codex 或 Cursor 中：

请按 PACT 对最近 3-5 个已发布功能做 retro。
检查意图漂移、契约质量、验证质量和活跃技术债。

.pact/knowledge/patterns.md 用来记录跨功能、跨会话仍然有效的工程知识：

  • 模块约定
  • 非显然依赖
  • 测试方式
  • 常见陷阱

稳定经验可在 /pact.ship 时沉淀，过时内容在 /pact.retro 中清理。不要把 patterns.md 当作进度日志、debug 草稿，或替代 AGENTS.md、constitution.md、模块 handover。

发布或共享框架变更前：

bash .pact/bin/pact-check.sh

在已安装 PACT 的业务项目中：

bash .pact/bin/pact.sh check --project

通过受控入口校验或更新 PACT 状态：

bash .pact/bin/pact.sh state validate
bash .pact/bin/pact.sh state enqueue <feature>
bash .pact/bin/pact.sh state set-phase <phase>
bash .pact/bin/pact.sh state complete
bash .pact/bin/pact.sh state fail-verify

诊断长期停滞状态，且不修改文件：

bash .pact/bin/pact.sh check --stale

检查 agent 入口文件：

bash .pact/bin/pact.sh lint-agents --all

检查 Global Spine Lite 产物：

bash .pact/bin/pact.sh lint-pad .pact/specs/PAD.md
bash .pact/bin/pact.sh lint-architecture .pact/core/architecture.md
bash .pact/bin/pact.sh lint-pid --all

如果项目采用 PACT 的 release 层，并维护 VERSION 与 CHANGELOG.md：

bash .pact/bin/pact-release-check.sh

7. 发布纪律

PACT 不要求每次文档或规则编辑都更新版本。

只有具备明确发布价值的一组变更才发版：

  • PATCH：已有行为、文档、模板或检查的修整
  • MINOR：完整新能力
  • MAJOR：不兼容协议或状态机变化

发布说明来自 CHANGELOG.md。

8. 进一步参考