メニュー
Project-aware expert-role contract design for APIs, interfaces, repositories, services, message schemas, and module boundaries. Reads project docs first, then produces or reviews a contract consistent with the current repository.
Codex または Claude でインストール この Prompt をコピーして Codex、Claude、または他のアシスタントに貼り付けると、Skill ページを確認してインストールできます。
SOC 職業分類に基づく
| name | api-design |
| description | Project-aware expert-role contract design for APIs, interfaces, repositories, services, message schemas, and module boundaries. Reads project docs first, then produces or reviews a contract consistent with the current repository. |
| argument-hint | Describe the boundary, interface, endpoint, message contract, or service behavior to design or review |
Produces a project-aware, expert-level contract design or design review by reading the repository's project docs first, then applying a reusable method to the current boundary type.
This skill is intentionally reusable across:
It should not assume one language, framework, transport, or architecture style until the project docs confirm them.
| Document | Why it matters |
|---|---|
docs/project-docs/foundation/architecture.md | Defines stack, architecture boundaries, dependency rules, and integration patterns |
docs/project-docs/foundation/prd.md | Clarifies scope, constraints, stakeholders, and non-goals |
docs/project-docs/development/testing.md | Defines how the contract should be validated |
| Relevant feature docs, API docs, or guidelines | Provide domain-specific rules, request/response shapes, workflows, and edge cases |
| Existing code or contracts in the repo | Show local naming, layering, serialization, validation, and error conventions |
If the repository lacks the contract-defining docs needed for the task, call that out and create or update the missing docs instead of inventing local rules in the skill.
Use this skill when designing or reviewing one of these boundary types.
| Boundary type | Typical artifacts |
|---|---|
| External HTTP / RPC API | route, handler, controller, request/response schema, auth, pagination, versioning |
| Internal service interface | method signatures, error contract, idempotency, retries, transaction boundaries |
| Repository or persistence boundary | interface, query contract, mapping rules, transaction semantics |
| Adapter or integration boundary | client interface, DTOs, transport mapping, failure translation |
| Event or message contract | payload schema, producer/consumer expectations, ordering, retry, dead-letter rules |
| Module boundary | public interface, dependency direction, allowed imports, extension points |
Determine which layer or module owns the boundary.
Questions to answer:
Use architecture.md to avoid violating the project's dependency or layering rules.
Extract from project docs:
Do not assume REST, JSON, SQL, Clean Architecture, CQRS, or any other pattern unless the docs require it.
Design the minimal contract that supports the required behavior.
Depending on the boundary, specify:
Prefer explicit types or schemas over ambiguous free-form payloads.
If the project distinguishes domain models from transport or persistence models, keep them separate.
Typical separations include:
Use the separation rules already defined by the project docs. Do not invent new layering rules casually.
Specify:
If the repo already defines a standard result wrapper, exception hierarchy, or error envelope, reuse it.
Use testing.md to decide how the contract should be validated.
Examples:
The output should fit the repository style and include enough detail to implement safely without locking the repo into one stack-specific pattern that the docs do not support.
When using this skill, the output should include:
Use this checklist when reviewing an existing contract:
testing.md?prd.mdWhen using this skill, the output should include:
@agent use api-design on [Target Entity/Feature] focusing on [Specific Constraints/Version].
Language-agnostic endpoint documentation generator. Reads routing and codebase to produce structured API contract documentation for existing endpoints.
Expert-role parity check across project docs, platform instruction surfaces, skills, reusable prompts, workflows, quick-reference material, and implementation evidence when authority depends on the current codebase. Use when checking whether the template system still agrees with itself or when preparing cleanup after major changes.
Project-aware expert-role broad verification that reads project docs first, classifies the verification target, and routes to the best specialist skill for executable or non-executable checks across code, contracts, docs, architecture, quality, security, reliability, and project health.
Project-aware expert-role database schema and modeling design. Reads project docs first, then produces a schema design, migration plan, or query optimization strategy consistent with the current repository constraints.
Project-aware expert-role for CI/CD pipeline design and implementation. Reads project docs first, enforces build caching, security gates, test execution, and deployment safety.
Project-aware expert-role for code refactoring. Reads project docs first, enforces TDD, and restructures code to reduce cyclomatic complexity and improve maintainability without altering external behavior.