contract-first SKILL.md skillA
contract-first from qshanx/docs-governance is an agent skill: a SKILL.md folder an AI agent loads when a task calls for it.
mdr add qshanx/docs-governance/contract-first@git:20261012.bd30f6ePins git:20261012.bd30f6e in mdr.lock. Pin the fingerprint instead.
- Audit grade
- A, 17 of 17 checks passed
- Kind
- SKILL.md skill
- Repository
- qshanx/docs-governance
- Path
skills/engineering/contract-first/SKILL.md- Versions recorded
- 4
- Latest version
- git:20261012.bd30f6e, committed Oct 12, 2026
- First version recorded
- Oct 11, 2026
- Size
- 12,290 bytes
- Repository stars
- 218
- License
- MIT
也适用于同一进程内存在明确消费者、提供者和公共接口且有漂移风险的业务模块；按实际边界验证公开签名与行为，无网络边界时不要求序列化证据。 分前端/后端（或多个服务）多端开发的项目，用 CONTRACT.md 指向的唯一机器契约，各端只照它各做各的，防止字段漂移导致集成时白屏。支持单会话多 agent 和多终端各自跑两种模式。只要项目有前后端/多服务、接口字段老对不上、各端联调卡住、某端改了字段忘了通知别人、或前端为渲染一个页面要调一堆接口拼数据，就用这个 skill，哪怕用户没明说"契约"。这套方法论的学名是消费者驱动契约（Consumer-Driven Contracts, CDC）/ 契约测试。中文触发：契约式开发、接口契约、前后端协作、多终端协作、防字段漂移、接口对不上、联调、API 契约、字段命名不一致、集成白屏、唯一真相源、契约测试、CDC。English triggers: contract-first development, consumer-driven contracts, contract testing, API contract, frontend…
Collected from public GitHub. Every version is saved exactly as it was and never changes. Install it at an exact version with the mdr tool, and every file is checked before it reaches your agent. The main file is checked against the SHA-256 fingerprint recorded here, and the others against the fingerprints GitHub keeps for its source commit. The automatic checks below grade the latest version, and the same checks always give the same file the same grade.
What the file says
# 契约优先（Contract-First / Consumer-Driven Contracts） 多端并行开发的项目（前端 + 后端，或再加多个服务），最容易炸在"连接"那一刻： > 后端把 `userName` 改成 `user_name`，忘了通知前端。两边各自"自测通过"，一集成——白屏。**两份文档各自为真，合起来是假的。** **契约优先**把接口当成一份**唯一机器契约**（由 `CONTRACT.md` 登记入口）：所有数据接口只定义一次，各端照它各做各的，谁都不许私自偏离。它和 `living-docs-governance` 是姊妹篇——那套防"项目文档"漂移，这套防"端与端之间的接口"漂移。 > 学名：这套就是 **消费者驱动契约（Consumer-Driven Contracts, CDC）/ 契约测试（contract testing）**。"消费方需求先行"=CDC 核心；"后端写返回符合契约的测试"=提供者验证（provider verification）；标杆工具是 Pact，契约规格常用 OpenAPI/Swagger。 ## 什么时候启用 - 项目分前端 + 后端（或多个服务），且各端可能**并行**开发。 - 接口字段老对不上：`userName` vs `user_name`、类型不符、枚举值不一致。 - 某端为渲染一个页面要调 5 个接口拼数据。 - 某端改了接口忘了通知别人，集成时才发现。 同一进程内的业务模块也可在存在明确消费者／提供者和公共接口时复用契约核对，不要求拆成服务。没有真实集成边界或漂移风险时，不为普通内部函数建立契约体系。 ## 模块入口复用 已有 `CONTRACT.md` 或接口登记位置就继续引用它。采用模块两入口布局且没有独立契约入口时，将路径、拥有者、版本依据、兼容约束和验证命令放在模块 `AGENTS.md` 的“接口契约”节；本 Skill 下文的 `CONTRACT.md` 均指这个已选定的入口，不要求再新建同名文件。字段不写两遍。 进程内接口可用已有公共导出／语言接口类型作为唯一机器定义，配消费者／提供者行为测试；跨网络接口仍验证线上的序列化 schema，内部 DTO 不能替代它。副作用、错误和状态流转若类型无法表达，以已有规格和测试为据并链接。术语归对应 `CONTEXT.md`，选型理由归 `domain-modeling` 管理的决策记录。 ## 两种协作模式（关键：选对你的现实） 这套契约协作有两种落地方式，纪律一致、组织方式不同： ### 模式 A — 单会话多 agent（中心化派活） …
Read the whole file at its exact version.
How to install
mdr add qshanx/docs-governance/contract-first@sha256:915f1db21b088988The line at the top of this page pins the label git:20261012.bd30f6e, which is what most people want. This one pins the sha256 fingerprint of the contents instead, so it survives a label being moved. Either way the exact version is written to mdr.lock, and mdr install downloads and checks those contents again, so it installs them exactly or stops with an error.
[](https://markdownregistry.com/a/art_b6ioesqafoj6mvlq)
1 badge image fetches in 30 days. What the badge shows.
Versions
The registry has recorded 4 versions of this file, between Oct 11, 2026 and Oct 12, 2026, more than one a day.
| version | committed | commit | size | audit | |
|---|---|---|---|---|---|
| git:20261012.bd30f6e latest | 2026-10-12 | bd30f6e | 12,290 B | A | view · diff |
| git:20261011.c5f9740 | 2026-10-11 | c5f9740 | 12,296 B | A | view · diff |
| git:20261011.d6d08d8 | 2026-10-11 | d6d08d8 | 11,469 B | A | view · diff |
| git:20261011.d0306dc | 2026-10-11 | d0306dc | 10,652 B | A | view |
Audit of the latest version
- pass: Frontmatter block present
- pass: Frontmatter declares a name
- pass: Frontmatter declares a description
- pass: Size between 200 bytes and 200 KB (12290 bytes)
- pass: No zero-width or bidi control characters
- pass: No instruction hidden inside an HTML comment
- pass: No link to an exfiltration or paste host
- pass: No credential-shaped string
- pass: No instruction to send local credentials anywhere
- pass: No text hidden with inline styles
- pass: No prompt-injection phrasing
- pass: No curl or wget piped into a shell
- pass: No recursive delete of root, home or parent
- pass: No instruction to read or print local credentials
- pass: No base64 blob over 200 characters
- pass: No link to a raw IP address
- pass: No script tag
Source
qshanx/docs-governance · 218 stars · license MIT · pushed 2026-10-16 · branch main
API
GET https://markdownregistry.com/api/v1/artifacts/art_b6ioesqafoj6mvlq GET https://markdownregistry.com/api/v1/resolve?ref=qshanx/docs-governance/contract-first GET https://markdownregistry.com/api/v1/blob/915f1db21b0889885a3ac0ead0c50cd948e366f7c3db6e87f21d7f2b4858f31d
Your AI assistant does the legwork. You hear about the deals worth your word. Hand yours the standing instructions at modelranch.com and it joins the network that reads files like this one.
Guides: the SKILL.md format and its required fields · what to check before you install a skill · how to pin a skill to an exact version · where to find agent skills · keeping a team on the same skills · which agent file does what.
More from qshanx/docs-governance
Every file in qshanx/docs-governance