菜单
Creates contract artifacts that define boundaries between components -- what they promise, what they expect, and what they explicitly exclude. Use when establishing or documenting how services, modules, or systems interact.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
| name | writing-contracts |
| description | Creates contract artifacts that define boundaries between components -- what they promise, what they expect, and what they explicitly exclude. Use when establishing or documenting how services, modules, or systems interact. |
A contract defines a BOUNDARY between components. It captures what one side promises and what the other side can depend on.
An external promise: one endpoint, event, interface, or integration point. It answers: "What can consumers depend on?"
A contract must include:
Good:
dna add contract \
"The user service exposes identity lookup. Callers provide an opaque user identifier. The service returns display identity (name, avatar) and contact identity (email). The service NEVER exposes authentication credentials or internal database identifiers. Callers must handle: not-found, rate-limited, unavailable. Response latency must stay under 50ms at p99." \
--name "User identity lookup" \
--label domain=users
This survives a rewrite from REST to GraphQL. It tells consumers what they can depend on and what they cannot.
dna add contract \
"The event bus guarantees at-least-once delivery. Consumers must be idempotent. Message ordering is guaranteed within a partition key but not across partition keys. Maximum message size is 1MB. Messages not acknowledged within 30 seconds are redelivered." \
--name "Event bus delivery guarantees" \
--label domain=infrastructure
This defines the contract without naming Kafka, RabbitMQ, or any specific technology.
Bad:
GET /api/v2/users/:id returns { id: number, name: string, email: string }
This is a schema snapshot, not a contract. It will be stale when you add a field. The contract should describe what categories of data are returned, not exact field names.
The user service is built with Express.js and uses MongoDB.
This is implementation, not a contract. Consumers should not know or care.
What a contract explicitly excludes is often more valuable than what it includes. Stating "NEVER exposes authentication credentials" prevents a future agent from adding a convenience endpoint that leaks tokens.
Always ask: "What must this component NOT do, even if it would be convenient?"
--format openapiFor API contracts, consider storing both: an OpenAPI spec for the machine-readable shape, and a markdown contract for the guarantees that OpenAPI cannot express (latency bounds, semantic invariants, failure mode expectations).
When your plan introduces or modifies an interface:
dna search "<the interface>" --kind contractInteractive conversation for deliberate truth changes. Acts as a truth guardian that searches DNA, surfaces conflicts, debates proposals, and only applies changes with explicit human reasoning. Use via text or voice mode in Claude Code.
Assembles DNA truth artifacts into a self-contained specification that an autonomous agent can execute against without further human guidance. Use when handing off a well-defined deliverable to an agent for extended autonomous execution.
Consults DNA truth artifacts during task planning to understand system identity before designing an implementation approach. Use at the start of any non-trivial task before choosing an architecture or decomposing work into steps. Searches for intents, contracts, and constraints that shape the solution space.
Creates escalation artifacts that define when an agent should stop autonomous work and involve a human. Use when encoding decision boundaries for agent autonomy -- the guard rails on what agents can decide alone.
Creates tradeoff artifacts that encode which concern wins when competing concerns clash. Use when two valid goals, constraints, or intents conflict and agents need to know which to prioritize.
Stores truth artifacts in DNA with correct kind, format, metadata, and semantic context. Use when codifying decisions, contracts, intents, or constraints that should persist across code changes, team transitions, and framework evolutions.
基于 SOC 职业分类
