Architecture-related changes must follow the specifications below.
Before coding
First draw the current → target dependency relationships and the change path, then write code.
SOLID principles
- Single responsibility: a module/class does only one thing, and changes have only one reason
- Open-closed principle: open for extension, closed for modification—new functionality is implemented through extension
- Dependency inversion: high-level modules do not depend on low-level modules; both depend on abstractions (interfaces/protocols)
Boundaries and layering
- Clear module boundaries, communicating through interfaces
- Dependency direction: outer layer → inner layer (UI → Service → Repository)
- Circular dependencies = architectural problems and must be resolved
- Separate configuration from code, manage with environment variables
Code organization
- Group by feature (feature-based), not by type
- Code size control (same as the HelloAGENTS coding principles): files/classes warn at 300 lines and require splitting at 400 lines; functions warn at 40 lines and require splitting at 60 lines. Exceptions: generated code, large test fixtures, migration scripts, protocol constant tables
- Extract common logic into shared/, but avoid premature abstraction
- Extract only after three repetitions—two similarities are not enough
Change strategy
- Assess the impact scope of the change (blast radius)
- Carry out large refactors in steps, and each step can be independently verified and rolled back
- Distinguish real external contracts from internal implementation inertia: real contracts such as public APIs, persisted data, documented integrations, and user commitments require compatibility and migration assessment; internal callers, old naming, old directory structures, and historical compatibility layers are not automatically preserved. When necessary, first determine the target model according to the core rules, then implement it along a phased path
Delivery checks
- No circular dependencies
- Files/classes do not exceed 400 lines, functions do not exceed 60 lines (except for exception types, non-minified code)
- Dependency direction is correct (outer → inner)
- Change scope is controllable
- The technical solution complies with the HelloAGENTS technology selection principles; if the current mode has not loaded the engineering quality lower bound in the implementation requirements, then at least satisfy the technology selection principles and ensure new projects have no outdated dependencies