data-contract
Skill0 starsChanged 3 months agoMITView on GitHub
Define or review a data contract between a producer and consumers. Use when creating a dataset, event stream, or API that another team depends on.
2 other projects use a version of this.
Adopted by
Most recently taken up by
- gmanch94/claude-code-aidlc-templatetheir own version, first seen Jul 11, 2026
- TheWatcher01/skillstheir own version, first seen Apr 1, 2026
Other versions2 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 2
- gmanch94/claude-code-aidlc-template★ 2same name
- TheWatcher01/skills★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository16 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .claude/commands/agents.mdAGENTS.md
- .opencode/AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- .github/copilot-instructions.mdCopilot instructions
- .cursor/rules/caveman.mdcCursor rule
- adrSkill
- agent-registrySkill
- cost-reviewSkill
- delegation-protocolSkill
- marketplaceSkill
- onboardingSkill
- orchestrationSkill
- postmortemSkill
- runbookSkill
- threat-modelSkill
The file
Files
Data Contract
The producer commits to a shape and a schedule. Consumers build against it. Breaking it without notice is an outage, not a refactor.
Template
name: <dataset or event name>
owner: <team, plus a named person>
description: <what it represents in business terms>
schema:
- name: <field>
type: <type>
nullable: <bool>
classification: public | internal | confidential | pii
description: <semantics, units, allowed values>
semantics:
grain: <one row per WHAT — answer this first>
primary_key: [<fields>]
late_arrival: <how late records are handled, and the cutoff>
timezone: <explicit. Never "local".>
sla:
freshness: <max lag, and what consumers should do when breached>
availability: <target>
completeness: <expected row count range>
quality_checks: [<the checks that gate publication>]
versioning:
policy: additive-only | versioned endpoints
deprecation_notice: <period>Worked example
Two versions of one field:
Ambiguous — three consumers will interpret it three ways:
- name: amount
type: decimal
description: The order amountWhich amount? Gross or net? Tax included? Which currency? Refunds negative or a separate row? Each consumer picks an answer, and the three dashboards disagree forever.
Unambiguous:
- name: amount_net_minor
type: integer
nullable: false
classification: internal
description: >
Order value excluding tax and shipping, after discounts, in the minor unit of
`currency_code` (cents for USD, yen for JPY — JPY has no minor unit, so the value
is whole yen). Always positive. Refunds appear as a separate row with
`transaction_type = 'refund'`, never as a negative amount here.
Range observed: 1 to 4_200_000.Plus the semantics that make it usable:
semantics:
grain: one row per order line item per transaction event
primary_key: [order_id, line_item_id, transaction_id]
late_arrival: >
Events up to 72h late are merged into their original partition, which is then
republished. Beyond 72h they land in the current partition with `is_backfill = true`.
Consumers reading a partition older than 72h can treat it as final.
timezone: All timestamps UTC. `order_date` is a date in the merchant's local
timezone — see `merchant_timezone`. These differ; do not join on them.That last line prevents a specific, expensive bug that would otherwise be found in production.
Breaking vs additive
| Change | Verdict |
| Add a nullable field | Additive |
| Add a non-nullable field | Breaking — old producers cannot fill it |
| Remove or rename a field | Breaking |
| Widen a type (int32 → int64) | Additive for readers, breaking for fixed-width writers |
| Narrow a type | Breaking |
| Change units, timezone, or semantics without renaming | Breaking, and the worst kind — nothing errors, everything is quietly wrong |
| Change the grain | Breaking. Every aggregate downstream is now wrong. |
The dangerous row is the semantic one. A rename fails loudly; a silent unit change corrupts six months of reporting before anyone notices.
Anti-patterns
| Anti-pattern | Why it fails |
| No grain stated | Consumers guess; their aggregates double-count |
status with undocumented values | Every consumer hardcodes a different subset |
| Timezone unstated or "local" | Off-by-one-day bugs at every month boundary |
| Contract in a wiki, not in the pipeline | Documentation drifts; tests do not |
| Nullable everything "to be safe" | Pushes every decision to consumers, who each decide differently |
| Classification added later | PII has already been copied everywhere by then |
Rules
- Grain first. "One row per what" is the first question and the most common omission.
- Classification at ingestion, never retroactively.
- The contract is enforced by tests in the producer's pipeline, not by a wiki page.
- Units in the field name where feasible:
amount_net_minor,duration_ms,weight_kg. - Breaking a contract without notice is treated as an outage, with a postmortem.
Done when
- Grain and primary key stated and verified unique against real data.
- Every field has semantics, units, and a classification.
- Timezone explicit for every temporal field.
- Late arrival and backfill behaviour documented.
- Quality checks run in the producer's pipeline and gate publication.
- A named owner exists — a team alone is not an owner.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

