Clean Architecture Requirements Build

Clean Architecture Requirements Build

Overview

Translate a requirement into explicit behavior, architecture boundaries, and production code. Reduce ambiguity before coding, then implement from stable use-case contracts outward.

Prefer explicit assumptions and small vertical slices over premature framework-heavy scaffolding.

Use clean-code-architecture-foundation when you need shared principles for choosing boundaries, sequencing work, or rejecting architecture theater.

Read references/clean-architecture-guidelines.md when you need first-principles guidance on the dependency rule, use-case boundaries, ports, adapters, and framework isolation. Read references/architecture-anti-patterns.md when a proposed design looks clean on paper but may be over-layered, framework-led, or hard to deliver. Read references/delivery-checklist.md when you need a compact quality gate before finalizing the design or code. Read references/operational-readiness-playbook.md when the slice involves rollout, migration, compatibility, authorization, observability, or production failure handling. Read ../clean-code-architecture-foundation/references/response-contract.md when you need the shared output format.

Request Fit

Use this skill for requests like:

• "Analyze this requirement, define the boundaries, and write the code."
• "Break this feature into use cases and implement it with clean architecture."
• "Design the ports and adapters for this workflow before implementation."
• "I need new behavior from this spec, not just a cleanup of the current code."
• "Clarify the acceptance criteria and then implement the smallest working slice."
• "Turn this product request into domain rules, contracts, and code."

Do not use this skill as the primary skill for requests like:

• "This controller is messy. Refactor it without changing behavior."
• "Find the code smell in this module and improve maintainability."
• "Review this existing code and reduce coupling."
• "Keep behavior the same and only clean up the structure."

Quick Routing

Prefer this skill when most of the user's value comes from turning an idea or spec into a clean implementation path.

• The user starts with a requirement, workflow, story, or API contract.
• The hard part is clarifying behavior and slicing the design.
• New code, new boundary contracts, or new business rules are expected.

Switch to clean-code-diagnose-refactor when:

• The user mainly wants review or cleanup of an already-existing implementation.
• The requested work can be completed by restructuring current code without product-scope expansion.
• The most important question is "what is wrong with this code?" rather than "what should we build?"

Workflow

1. Distill the requirement

• Extract goals, actors, inputs, outputs, constraints, and failure cases.
• Convert vague requests into testable acceptance criteria.
• State assumptions clearly when requirements are incomplete.
• Produce a compact requirement summary before coding so the user can see what will actually be built.
• Surface operational constraints early: authentication, authorization, migration impact, rollout, observability, performance, and failure recovery.
• If release constraints dominate the risk, treat them as first-class requirements rather than implementation notes.

Read references/requirements-template.md when the request is underspecified.

2. Model the architecture slice

• Identify entities, value objects, use cases, ports, adapters, and boundary DTOs.
• Decide what belongs to domain policy versus orchestration versus infrastructure.
• Keep dependencies pointing inward. Let outer layers implement interfaces required by inner layers.
• Do not create separate files, classes, ports, or adapters by default when a small slice is still clearer as one cohesive module.
• Keep tiny interfaces, thin adapter scripts, and one-off boundary glue in the same file as the owning slice until separate evolution is actually needed.
• Use references/clean-architecture-guidelines.md to check whether the slice is truly driven by business rules rather than framework convenience.
• Use references/architecture-anti-patterns.md to reject layers or abstractions that do not protect a real boundary.

Read references/architecture-mapping.md when mapping requirements to layers.

3. Choose the implementation seam

• Start from the use case or domain rule that carries the business value.
• Define input and output contracts before wiring transport or persistence.
• Implement only the slice required for the requested behavior, not a speculative platform.
• Favor one vertical slice that can be verified end to end over broad scaffolding with little executable value.
• Use references/operational-readiness-playbook.md when choosing the slice depends on rollout safety, migration sequencing, compatibility windows, or observability coverage.

4. Write code with clean boundaries

• Keep business rules free from framework types and transport details.
• Use adapters for databases, APIs, queues, files, and UI concerns.
• Translate between external schemas and internal models at boundaries.
• Prefer simple composition over inheritance-heavy design.
• Prefer the smallest cohesive set of files that expresses the current slice clearly, and delay further splitting until independent reasons to change actually appear.
• Prefer one cohesive file for tiny ports, boundary types, or scripts when splitting them would only add file hops without making the design safer.
• If requirements remain ambiguous, encode the decision as an explicit assumption or TODO at the edge, not as fuzzy domain logic.
• Keep release controls such as feature flags, migration toggles, and compatibility adapters at the edge rather than leaking them into core policy.

5. Verify against the requirement

• Test the use case behavior first.
• Add boundary-level tests where integration risk is real.
• Check that acceptance criteria, error paths, and invariants are covered.
• Verify operational readiness where relevant: auth behavior, compatibility assumptions, migration/backfill safety, observability hooks, and rollback posture.
• Use references/delivery-checklist.md before concluding that the architecture is complete.

6. Report the result

• Summarize assumptions, architectural decisions, implemented behavior, and verification status.
• Call out missing requirement details that still need a product or domain decision.
• Distinguish clearly between code written for the current slice and deferred architecture.

Output Shape

When the task includes analysis plus implementation, structure the response in this order:

1. Requirement summary
2. Assumptions and gaps
3. Architecture slice
4. Implementation plan or code change
5. Verification status
6. Open decisions

If the user provides only a rough idea, return a tightened requirement and acceptance criteria before expanding into architecture.