ai-agents unified-software-engineering.instructions.md

Unified Software Engineering

This rule resolves conflicts between engineering principles that models already know (Clean Code, DDD, Refactoring, Pragmatic Programmer, Code Complete) so that contradictions do not produce inconsistent agent behavior. Use it as a tiebreaker and as a concrete blocklist when reviewing or generating code.

Cherry-picked from agent-rules-books (MIT). The full upstream document is intentionally not imported. Adding the entire 46KB rule set duplicates content already known to the model and degrades response quality.

Primary Directive

When uncertain, choose the option that makes the system easier to understand, safer to change, and more honest about its real constraints.

Prefer designs that:

1. reduce the number of facts a reader must hold at once
2. put each business rule in one authoritative place
3. keep volatile details behind stable boundaries
4. make data ownership and consistency explicit
5. survive partial failure, retries, and operational stress
6. preserve behavior during structural change
7. shorten feedback loops

Reject designs that merely appear simpler by hiding complexity in callers, frameworks, databases, global state, queues, or operational assumptions.

Conflict Resolution Rules

Apply these rules when engineering principles appear to disagree.

Simplicity vs Rich Modeling

• Use the simplest design that honestly represents the problem.
• Simple CRUD or administrative workflows may use transaction scripts or simple service-layer code.
• Complex business rules, lifecycles, invariants, and language distinctions require richer domain modeling.
• Do not use DDD patterns as ceremony in generic or low-complexity subdomains.
• Do not flatten real domain complexity into passive records and procedural services.

Small Functions vs Deep Modules

• Functions and routines should be cohesive and understandable.
• Prefer small units when they clarify intent, isolate responsibility, or simplify testing.
• Avoid chains of tiny pass-through functions that force readers to jump constantly.
• A module may contain internal complexity when its public interface is small, meaningful, and stable.