Run any Skill in Manus with one click

interface-first-development

Stars4

Forks0

UpdatedMay 30, 2026 at 04:02

Defines module specs (a README that says what the module owns AND does NOT own) and typed contracts before any implementation, then drives the Spec -> Interface -> Tests -> Implementation loop. Use this when starting a new module, service, feature, component, or API client; when deciding "where does this logic live?"; when two pieces of code need a commission-rate / shared-value boundary; when writing or reviewing a module/feature README; or when defining backend service interfaces (Protocols, interfaces.py) or frontend contracts (component props/events, typed API clients) — even if the user never says "interface-first" or "contract."

Installation

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

Run Skill in Manus

Source

yongkangzhao

yongkangzhao/Vibe-Coding-Standards-and-Guidelines

View GitHub Repository View Creator Repositories

Download

Run Skill in Manus

Related occupationsSOC

Based on SOC occupation classification

Software DevelopersComputer and Mathematical Occupations·SOC 15-1252

File Explorer

3 files

SKILL.md

readonly

name

interface-first-development

description

Interface-First Development

Write the contract before the code: a spec that states what a module owns and explicitly does NOT own, a typed interface that locks scope, then tests, then implementation — in that order. This matters most when AI agents write the code, because an agent starts every session fresh with no institutional memory. Without a spec and interface already in place, it designs on the fly from local context and re-litigates decisions the team already made — fast, confidently, and three times over.

When to use this

Starting a new backend module or service — before writing service.py, write its README and its interfaces.py entry.
Starting a new frontend feature or component — before writing the component, define its prop/event contract, its typed API-client interface, and a feature README.
Someone asks "where should this logic live?" or the same value (a commission rate, a discount, a status) is about to be computed in two places.
Reviewing a module/feature README, or a PR that adds public methods, props, or endpoints.
Coordinating parallel work — two agents or two people need to build against each other without direct coordination.

The standards

Write the README as an executable spec, owns AND does-NOT-own. For agents, documentation IS the specification — they read it instead of carrying months of context. The does-NOT-own section is what stops an agent from optimizing locally and dropping logic into the nearest plausible module.

# <module> README
Role:            one paragraph — what this module owns
Does NOT own:    explicit non-ownership (e.g. "pricing lives in billing, not here")
Public interface: every method/prop/endpoint — what it does, what it raises/returns
Data:            tables or state it stores
Dependencies:    what other services/contracts it requires
Test command:    how to run this unit's tests in isolation

Define the interface before any implementation exists. The contract is the AI-to-AI communication protocol: if a method isn't in the interface, it isn't part of this unit — no ambiguity, nothing to invent mid-build.

interface OrganizationService:
    get_commission_rate(org_id) -> Decimal      # the ONLY place this value lives
    # backend: a Protocol/interface in a shared contracts file
    # frontend: a typed component prop/event contract + a typed API-client interface

Let the contract end the question, not find the perfect answer. The commission-rate value comes from exactly one method, so every caller uses it — closing an architectural debate that would otherwise be re-asked and re-implemented by each fresh agent.

# without a contract: rate lives in 3 modules, 2 wrong, every PR an argument
# with a contract:    callers do org_service.get_commission_rate(org_id) — done

Follow the loop in order: Spec -> Interface -> Tests -> Implementation. By the time implementation begins, three layers of constraints already define "correct," so the agent's only job is to satisfy them — there is no design work left to improvise.

1. Spec          README: owns / does NOT own
2. Interface     signatures in the shared contracts file — before service code
3. Tests         written against the interface; MUST fail first (stubs raise NotImplemented)
4. Implementation make the failing tests pass, within the constraints already set

Build against interfaces, not implementations, to unblock parallel work. Agent A builds the task module and Agent B builds notification, each against the same contracts file; they never coordinate directly and still compose at the wiring root.

Checklist

README exists and has both a "Role / owns" and an explicit "does NOT own" section.
Every public method/prop/endpoint appears in the contract before its implementation.
Each shared value (rate, price, status) is owned by exactly ONE interface method.
Tests were written against the interface and observed FAILING before implementation began.
No design decisions were made during implementation — only build work to pass tests.
Callers depend on the interface/contract, not on a concrete class or component internals.

What breaks without this

Feature duplication: the same logic (fetch active subscription, compute a rate) lands in three files written at different times; billing changes, one gets updated.
The re-litigated decision: where the commission rate lives gets re-asked by every fresh agent; you end up with three implementations, two wrong, and every PR becomes an architectural argument.
Design-on-the-fly drift: with no spec or interface in place, an agent invents architecture mid-implementation that reflects local context, not the global decisions already made.
Logic leakage: without a does-NOT-own boundary, business rules bleed into handlers, components, and queries — each with subtly different behavior, none authoritative.

Stack-specific examples

Backend: see references/backend.md — interfaces.py Protocols, a module README template, a failing test stub raising NotImplementedError.
Frontend: see references/frontend.md — TypeScript interfaces/types, a typed API client, component prop contracts, a feature README template.

Full rationale: docs/04-structural-guidelines.md (Standards 4 and 5), docs/05-development-loop.md (Standard 10), and docs/02-what-breaks.md (the commission-rate example) in this repo.
tests-as-ground-truth and superpowers:test-driven-development for the red-green test mechanics of step 3 — write the tests there; this skill only requires that they exist and fail first.

More from this repository

same repository

adversarial-exploit-review

yongkangzhao/Vibe-Coding-Standards-and-Guidelines

Independent adversarial review that proves findings with failing exploit tests rather than prose — a reviewer who did NOT write the code writes tests designed to make it fail, the engineer fixes until they pass, and high-risk surfaces get multiple reviewers with distinct failure lenses. Use this when reviewing or merging a change, auditing a module, hardening auth/RBAC/money/migration/data-loss code, deciding whether one review pass is enough, writing a security or exploit test, mutation-testing a guard, or handling a non-blocking finding — on backend OR frontend, even if the user doesn't say "adversarial review."

2026-06-114

clean-migration

yongkangzhao/Vibe-Coding-Standards-and-Guidelines

When you change an architecture, migrate EVERY call site in the same change and delete the old path — no dual-path codebase, no "backward compat" bypass kwarg, no re-export shim. Use this when making a parameter required, ripping out a concept, promoting duplicated code to one shared copy, renaming a route or type, or choosing between a real migration and a clever in-place patch — for both backend and frontend, even if the user doesn't say "migration."

2026-06-114

frontend-honesty

yongkangzhao/Vibe-Coding-Standards-and-Guidelines

Forbids the UI from ever displaying something untrue — fabricated zeros for missing data, a failed fetch shown as an empty list, a raw identifier shown as a name, or a number coerced from garbage. Use this when building or reviewing any view that renders a value, money, count, rating, or status; when writing a number/money/percent formatter; when handling loading/empty/error states; when mapping a backend error to on-screen copy; or whenever an agent is about to render a plausible-looking value with no real data behind it — for both backend (what the API returns) and frontend (what the screen shows), even if the user doesn't say "honesty."

2026-06-114

server-authoritative-state

yongkangzhao/Vibe-Coding-Standards-and-Guidelines

Treats the client as a cache of the server's truth — mutations reflect the server's returned result (never an assumed outcome), the cache is written from confirmed responses, and authority (permissions, prices, availability, membership) comes from the server, not client derivation. Use this when writing or reviewing an optimistic update, a mutation handler, a delete/remove-from-list flow, a refetch/invalidation, a double-submit guard, a replace-all editor, or any place the UI shows derived state — and when designing the endpoints that back them — for both backend and frontend, even if the user doesn't say "server-authoritative."

2026-06-114

verify-through-the-real-path

yongkangzhao/Vibe-Coding-Standards-and-Guidelines

Insists that "it works" be proven through the actual request path, the deployed artifact, and the genuine UI — not inferred from green unit tests that mocked the exact seam that breaks. Use this when deciding whether a feature is done, reviewing a change that "passes all tests," wiring or trusting CI/CD, mocking the network or auth in a test, debugging a live bug that grep says shouldn't exist, or choosing what evidence counts as proof — for both backend and frontend, even if the user doesn't say "verify through the real path."

2026-06-114

agent-team-review-loop

yongkangzhao/Vibe-Coding-Standards-and-Guidelines

Structures multi-agent work into bounded tasks, tool-restricted roles, and an iterative review cycle that loops until reviewers report clean. Use this when dispatching agents to build or change code (frontend or backend), when an agent is about to both write and review its own work, when scoping a task like "implement the notification module" vs "improve the app", when two agents might write the same test file, when an agent builds a React feature and then needs an independent pass for accessibility or business-logic leak, or when deciding whether to commit after one review pass — even if the user doesn't name it explicitly.

2026-05-304

name

interface-first-development

description

Interface-First Development

Write the contract before the code: a spec that states what a module owns and explicitly does NOT own, a typed interface that locks scope, then tests, then implementation — in that order. This matters most when AI agents write the code, because an agent starts every session fresh with no institutional memory. Without a spec and interface already in place, it designs on the fly from local context and re-litigates decisions the team already made — fast, confidently, and three times over.

When to use this

Starting a new backend module or service — before writing service.py, write its README and its interfaces.py entry.
Starting a new frontend feature or component — before writing the component, define its prop/event contract, its typed API-client interface, and a feature README.
Someone asks "where should this logic live?" or the same value (a commission rate, a discount, a status) is about to be computed in two places.
Reviewing a module/feature README, or a PR that adds public methods, props, or endpoints.
Coordinating parallel work — two agents or two people need to build against each other without direct coordination.

The standards

# <module> README
Role:            one paragraph — what this module owns
Does NOT own:    explicit non-ownership (e.g. "pricing lives in billing, not here")
Public interface: every method/prop/endpoint — what it does, what it raises/returns
Data:            tables or state it stores
Dependencies:    what other services/contracts it requires
Test command:    how to run this unit's tests in isolation

interface OrganizationService:
    get_commission_rate(org_id) -> Decimal      # the ONLY place this value lives
    # backend: a Protocol/interface in a shared contracts file
    # frontend: a typed component prop/event contract + a typed API-client interface

# without a contract: rate lives in 3 modules, 2 wrong, every PR an argument
# with a contract:    callers do org_service.get_commission_rate(org_id) — done

1. Spec          README: owns / does NOT own
2. Interface     signatures in the shared contracts file — before service code
3. Tests         written against the interface; MUST fail first (stubs raise NotImplemented)
4. Implementation make the failing tests pass, within the constraints already set

Checklist

README exists and has both a "Role / owns" and an explicit "does NOT own" section.
Every public method/prop/endpoint appears in the contract before its implementation.
Each shared value (rate, price, status) is owned by exactly ONE interface method.
Tests were written against the interface and observed FAILING before implementation began.
No design decisions were made during implementation — only build work to pass tests.
Callers depend on the interface/contract, not on a concrete class or component internals.

What breaks without this

Feature duplication: the same logic (fetch active subscription, compute a rate) lands in three files written at different times; billing changes, one gets updated.
The re-litigated decision: where the commission rate lives gets re-asked by every fresh agent; you end up with three implementations, two wrong, and every PR becomes an architectural argument.
Design-on-the-fly drift: with no spec or interface in place, an agent invents architecture mid-implementation that reflects local context, not the global decisions already made.
Logic leakage: without a does-NOT-own boundary, business rules bleed into handlers, components, and queries — each with subtly different behavior, none authoritative.

Stack-specific examples

Backend: see references/backend.md — interfaces.py Protocols, a module README template, a failing test stub raising NotImplementedError.
Frontend: see references/frontend.md — TypeScript interfaces/types, a typed API client, component prop contracts, a feature README template.

Full rationale: docs/04-structural-guidelines.md (Standards 4 and 5), docs/05-development-loop.md (Standard 10), and docs/02-what-breaks.md (the commission-rate example) in this repo.
tests-as-ground-truth and superpowers:test-driven-development for the red-green test mechanics of step 3 — write the tests there; this skill only requires that they exist and fail first.