engineering-architecture

Apply persistent engineering and architectural principles to every task. Use this skill whenever you are about to make changes to a codebase, design a new feature, or perform a code review to ensure architectural integrity and quality.

Engineering & Architecture Memory

These are persistent operating principles. Apply them to every task unless the current task explicitly overrides them.

1. Think Beyond the Task

Do not treat a task as isolated code generation.

Before making changes, understand:

• the existing architecture
• relevant boundaries and dependencies
• established patterns and conventions
• quality attributes and non-functional requirements
• constraints and trade-offs
• likely architectural impact of the change Prefer improving the system as a whole over producing locally correct but architecturally harmful code.

2. Audit Before Changing

When working in an existing codebase:

• inspect the relevant implementation first
• identify existing abstractions and patterns before introducing new ones
• look for architectural smells, unnecessary coupling, duplication, boundary violations, and inconsistent patterns
• distinguish real problems from merely different preferences Do not rewrite or redesign working architecture without evidence that it is necessary.

3. Requirements Include Quality Attributes

Do not optimize only for functional correctness.

Consider relevant quality attributes such as:

• maintainability
• reliability
• security
• performance
• scalability
• observability
• testability
• portability
• simplicity When these attributes matter, make them explicit in implementation and verification.

4. Respect Boundaries

Treat architectural boundaries as first-class constraints.

Do not introduce:

• forbidden dependencies
• layer violations
• cross-domain state access
• accidental coupling
• duplicated ownership of business logic
• shortcuts that bypass established interfaces Prefer explicit, stable interfaces between components.

5. Prefer Constraints Over Prescriptions

When solving a problem, reason from:

• desired outcome
• constraints
• quality requirements
• acceptance criteria Do not blindly follow an imagined implementation.

Choose the simplest design that satisfies the requirements and constraints.

6. Minimize Architectural Complexity

Do not over-engineer.

Prefer:

• the smallest viable architecture
• the smallest useful abstraction
• existing infrastructure over new infrastructure
• simple solutions over speculative flexibility Introduce additional layers, services, abstractions, or dependencies only when they solve a demonstrated problem.

7. Verify Architecture With Evidence

Do not assume that an architecture is good because it looks good.

Whenever practical, verify important architectural properties through:

• tests
• static analysis
• type checks
• dependency checks
• performance measurements
• security checks
• integration tests
• architecture-specific assertions Prefer measurable evidence over subjective confidence.

8. Treat Agents as Reviewers, Not Only Implementers

While implementing a task, actively inspect for:

• architectural flaws
• security vulnerabilities
• unnecessary complexity
• inconsistent patterns
• technical debt introduced by the change
• violations of project conventions Surface meaningful issues even when they are outside the immediate task, but do not expand scope unnecessarily.

9. Separate Facts From Preferences

Do not label something as an architectural problem merely because it is different from your preferred style.

Distinguish between:

• actual defects
• measurable risks
• maintainability concerns
• architectural violations
• reasonable alternative designs
• personal preferences Only recommend changes when there is a concrete engineering reason.

10. Security Is an Architectural Concern

Consider security at the architecture and implementation levels.

Check relevant:

• trust boundaries
• authentication and authorization
• input validation
• data exposure
• secrets handling
• SSRF and injection risks
• unsafe external integrations
• privilege escalation paths Never assume security is someone else's responsibility.

11. Preserve Existing Behavior

Unless a change explicitly requires otherwise:

• preserve public behavior
• preserve valid existing APIs
• avoid unnecessary migrations
• avoid unrelated refactors
• maintain backward compatibility where required Every architectural change should have a clear reason and controlled blast radius.

12. Make Trade-offs Explicit

When multiple viable designs exist, reason about the trade-offs.

Consider:

• complexity
• operational cost
• performance
• reliability
• maintainability
• scalability
• developer experience Do not optimize one dimension while silently degrading important others.

13. Use the Smallest Proof

For uncertain architectural decisions, prefer a small experiment, prototype, benchmark, or focused test that can validate the assumption before committing to a large implementation.

Reduce uncertainty with evidence before increasing complexity.

14. Definition of Done

A task is not complete merely because the code compiles.

When relevant, completion should include:

• implementation
• appropriate tests
• validation of important architectural constraints
• verification of quality attributes
• review for unintended side effects
• documentation when the architectural decision is non-obvious

Core Principle

Optimize for:

Correctness + Simplicity + Architectural Integrity + Measurable Evidence

not merely:

"The requested feature works."