Identify the existing architecture before adding code. Name it with evidence: the directory layout, the direction of imports between layers, where a similar feature already lives, and any architecture tests or import rules. Do not infer it from folder names alone.
Copy the nearest existing feature's shape. Put the new code in the same layers, with the same kinds of types, names, and wiring. A second way of doing the same thing is a cost every later reader pays.
Keep dependencies pointing inward. Domain and application code import no framework, database, HTTP, UI, or file system types. Adapters depend on the core, never the reverse.
Domain rules live in the domain or application layer, not in controllers, views, view models, handlers, or SQL. A controller or view parses input, calls one use case, and maps the result.
Do not invent a pattern or a layer the codebase does not use. A port with one adapter and no test double, a factory with one product, or a strategy with one strategy is speculative generality. Add the second implementation first, or ask.
Prefer the language feature to the GoF pattern: a function for a one-method Strategy or Command, a sum type and match for a closed Visitor, a module or dependency injection for a Singleton.
Follow the codebase's architecture unless it causes a defect. Then use the sound form in touched code, name the problem with evidence (file:line, how often it appears, and its maintenance cost), and ask before migrating untouched code. Never start an architecture migration unasked.
Check dependency direction with a tool when the repository has one (import-linter, dependency-cruiser, ArchUnit, NetArchTest, crate boundaries), and run it after the change.
Report the architecture you identified, where the new code went and why, each rule or tool check you ran with its result, and each check you skipped by name.

Workflow

Map the codebase: entry points, layers or modules, and which imports which. Read one existing feature end to end, from entry point to storage.
Name the style and the evidence. If the codebase mixes styles, name the one the nearest feature uses and say so.
Place each new type: which layer, which existing interface it implements or calls, and which files change. If the change needs a new layer, port, or pattern, ask first.
Write the code, then the architecture check and the tests for each layer you touched.
Report.

References

Read references/ports-and-layers.md for hexagonal, clean, onion, or layered codebases, and for dependency-direction tools.
Read references/ui-patterns.md for MVC, MVP, or MVVM code, and for where logic goes in a screen, view, controller, or view model.
Read references/gof-patterns.md before adding or naming a GoF pattern, to check it fits and is not over-engineering.
Read references/ecs.md for entity component system code (Bevy, flecs, Unity Entities).
Read references/file-layout.md when creating a source file or reordering one, then the file for its language: C, C++, C# and F#, Go, JS and TS, Java, Kotlin, Scala, Lua, Python, Ruby, Rust, Swift.

apply-architecture-patterns

Apply Architecture Patterns

Rules