# API Contract Agent Runbook

## Project Context To Prepare
- Project goal
- Current repository or workflow context
- Current context
- Goal
- Audience or stakeholder
- Constraints
- Available notes or data

## Input Template
Project:

Goal:

Current context:

Constraints:

Available files, notes, or data:

Expected output:
- API contract
- Endpoint specs
- Error codes
- Example requests and responses

## Starter Inputs
### First useful run
Use this when you know the goal but still need a structured first draft.

Draft an API contract for submitting new agent ideas with moderation status.

Context:
- Current state:
- Constraints:
- Audience:
- Success criteria:

### Project handoff run
Use this when the output will be pasted into a ticket, PR, document, or project brief.

Goal: produce API contract for a real project.
Source material:
- 
Constraints:
- 
Review needs:
- Go deep on the risks and constraints listed above.
- Mark assumptions.
- Flag missing context.

### Boundary check
Use this when the request may be under-specified and you want the agent to narrow it safely.

Invent a full billing API without pricing rules or account model.

Before producing the final answer, identify missing required context and propose a stronger prompt if needed.

## Setup Context Notes
- Prepare domain rules, request examples, response needs, auth assumptions, and error cases.
- Include the target audience, output destination, and any examples of acceptable or unacceptable work.
- Name what should remain out of scope so the agent does not broaden the task.

## Good Input Example
프론트엔드와 백엔드가 병렬 개발을 시작하는 상황

Goal: produce API contract for a real project.
Constraints: keep the result specific, structured, and ready for handoff.

## Weak Input Example
Help me with API Contract Agent.

## Weak Input Diagnostics
### Help me with API Contract Agent.
- Why it fails: It does not name the project, source material, constraints, audience, or success criteria.
- Stronger input: Draft an API contract for submitting new agent ideas with moderation status. Include current context, constraints, expected output, and review criteria.

### Make this better.
- Why it fails: The agent cannot tell whether better means clearer, safer, faster, more complete, or easier to hand off.
- Stronger input: Improve the output for 프론트엔드와 백엔드가 병렬 개발을 시작하는 상황. Optimize for API contract, keep assumptions explicit, and list the changes made.

## Expected Output Shape
- Conventions: base URL, auth, headers, CORS, rate limits, error format, naming and time formats
- Endpoints: method and path, request and validation, success response, every error with status and error code, and example JSON
- Behavior rules: idempotency, limits, ordering, merging, and what happens at each limit
- Open questions only when they block implementation
- Suggestions kept to one line each under "Suggested (not required)"

## Output Checklist
- Every stated decision and limit is applied to each endpoint it touches, with its status and error code
- The user's formats (casing, error envelope, time format) are kept exactly
- Examples are valid JSON and consistent with the rules
- No fields, endpoints, or behavior were invented; suggestions sit under "Suggested (not required)"
- Anything outside the stated scope is marked out of scope instead of designed

## Failure Modes
- A stated limit or rule has no error code or example
- Examples contradict the stated rules or formats
- The contract invents fields, endpoints, or behavior the user did not ask for
- The contract designs features outside the stated scope

## Handoff Tips
- Paste relevant project files, notes, or constraints before asking for the final output.
- Ask for a first draft, then request a stricter revision using the checklist.
- Keep the generated output with the project ticket, PR, proposal, or team document.