# Architecture Author

> Design the smallest architectural change that satisfies a settled requirement contract. Use when a requirement contract exists and the structure of the change needs deciding.

- Skill: `z-cursor/architecture-author` (Agent Skill)
- Install (CLI): `npx skillmds@latest add z-cursor/architecture-author`
- Raw SKILL.md: https://api.skillmd.com/api/skills/z-cursor/architecture-author/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: z-cursor (https://skillmd.com/u/z-cursor)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/z-cursor/architecture-author

---


Design the smallest architectural change that satisfies the settled requirement contract. /codebase-design supplies the vocabulary and principles: depth, seam, leverage, locality.

The inputs are the requirement contract and the repo. Read only what you need to establish current modules, interfaces, dependencies, and state ownership.

## Defaults

Prefer, in order:

1. KEEP EXISTING
2. SMALL LOCAL CHANGE
3. MOVE RESPONSIBILITY
4. CHANGE BOUNDARY
5. ADD ABSTRACTION

New abstractions start with a budget of zero. They prove themselves or they do not appear.

## Abstraction evidence

Introducing a service, manager, repository, adapter, provider, base class, interface, event bus, shared store, or framework layer requires stating in the contract:

- the observed problem — the real complexity it addresses
- the observed variation — the change axis actually seen
- before and after: change points, dependencies, state owners, duplicated knowledge
- what it deletes

The question that matters: what does this abstraction delete? If the answer is "it will make future changes easier" while there is one implementation, no duplicated knowledge, and no real variation, it is speculative. Drop it.

## Compare

For any consequential design, compare before and after on change amplification, cognitive load, unknown unknowns, dependency count, change surface, concept count, and state owners. Adding concepts without reducing change surface is complexity relocation, not reduction.

## Boundaries

State ownership is yours to decide: who owns, who mutates, who reads, who persists, who owns the lifecycle. More than one owner of the same business state is a risk.

Business truth is not yours. If the contract is ambiguous on behavior, return the specific gap to requirements — fill nothing, rewrite nothing.

## Design it twice

For a consequential seam or interface decision, produce at least two genuinely different candidates — different seam placement or different interface — and compare on depth, locality, change surface, information hiding, dependency direction, and state ownership. Renaming one design is not a second design.

## Handover

Write the architecture contract to a markdown file the user names:

<contract-template>

## Scope

## Requirement References

## Current Architecture Facts

## Chosen Boundary

## Module Responsibilities

## State Ownership

## Inputs / Outputs

## Dependency Direction

## Allowed Dependencies

## Forbidden Dependencies

## Interfaces

## Migration Boundary

## Abstractions Added

## Abstractions Rejected

## Rejected Alternatives

## Complexity Rationale

## Known Risks

## Open Architecture Questions

</contract-template>