Software Design Engineering

Software Design Engineering

Purpose

Use this skill to make software changes safer, simpler to maintain, easier to test, and easier to change later.

A good result is not just working code. It should also preserve or improve the codebase's long-term health.

When to use

Use this skill for:

• architecture or technical design planning
• non-trivial feature implementation plans
• refactoring strategy
• code review with maintainability concerns
• debugging where root cause and boundaries matter
• test strategy or verification planning
• changes touching multiple modules, layers, data models, APIs, or integration points

When not to use

Do not use this skill for:

• simple typo or syntax fixes
• formatting-only edits
• pure prose writing
• framework, library, or API documentation lookup
• tasks where a specialized framework skill is clearly more relevant
• edits where the correct answer is a single obvious local change

For small coding tasks, apply the principles lightly without adding process overhead.

Reference loading rules

Use SKILL.md as the control plane. Load only the references that match the task. Do not keep every reference in context by default.

For architecture, boundary, or module-design tasks, load:

• references/boundaries.md
• references/anti-patterns.md
• references/deep-design-heuristics.md

For code review tasks, load:

• references/code-review-rubric.md
• references/anti-patterns.md
• references/final-reporting.md

For refactoring tasks, load:

• references/refactoring-protocol.md
• references/boundaries.md
• references/testing-strategy.md

For debugging or root-cause tasks, load:

• references/debugging-protocol.md
• references/testing-strategy.md
• references/anti-patterns.md if the likely cause involves coupling, duplicated rules, hidden state, or weak boundaries

For test-planning tasks, load:

• references/testing-strategy.md
• references/boundaries.md if tests need to separate unit, integration, contract, and end-to-end coverage

For final implementation summaries or review reports, load:

• references/final-reporting.md

Load references/deep-design-heuristics.md when the user asks for deep design critique, when two viable designs look similar, when an abstraction may be shallow, or when the key decision is about hiding complexity rather than merely moving code.

If a task is simple enough to answer without a reference, do not add unnecessary ritual. Apply the smallest useful subset of the workflow.

Core directive

Before recommending or making a non-trivial change, evaluate:

Does this change make the system simpler or more complicated?

Prefer changes that:

• preserve or improve the system's design, not only its file layout
• localize complexity
• expose simple interfaces
• hide implementation details
• reduce cognitive load
• avoid duplicated knowledge
• make behavior testable
• keep likely future changes localized

Reject or redesign changes that:

• preserve behavior by spreading complexity instead of containing it
• make a route, controller, component, or script own too many responsibilities
• duplicate business rules or important constants
• leak database, API, provider, or file-format details across layers
• require callers to remember fragile sequencing
• add shallow abstractions that do not hide real complexity
• rely on unverified assumptions, arbitrary delays, or coincidence

Operating workflow

1. Identify the real problem

Do not immediately implement the surface-level request. First infer the actual engineering problem:

• user-facing need
• bottleneck or failure mode
• affected layers
• risk level
• whether this is prototype, tracer bullet, production feature, bug fix, or refactor
• smallest durable improvement

If context is incomplete but enough to proceed, state assumptions and continue.

2. Inspect existing design

Before changing code, inspect:

• folder and module boundaries
• naming conventions
• domain model and DTO shapes
• API contracts
• existing tests and scripts
• project guidance such as README, AGENTS.md, architecture notes, or roadmap docs
• similar code that already establishes a pattern

Follow existing conventions unless they are clearly harmful.

3. Design twice for non-trivial changes

For medium or large work, compare at least two viable approaches. Evaluate each by:

• interface simplicity
• change amplification
• cognitive load
• testability
• dependency direction
• blast radius
• future flexibility

Choose the design with the simplest durable interface, not necessarily the fewest lines of code.

4. Keep boundaries clean

Default boundary model:

UI/component layer:
  presentation, interaction, local UI state

API/controller/route layer:
  request parsing, validation, authorization boundary, response formatting

Service/domain layer:
  workflow orchestration, business rules, domain decisions

Repository/data-access layer:
  database queries, persistence details, schema-specific operations

Integration/client layer:
  external APIs, model providers, network concerns, file-system adapters

Utility/module layer:
  focused reusable logic with a clear contract

Do not force every codebase into these exact names. Preserve the underlying separation of concerns.

5. Prefer deep modules

A useful module hides meaningful complexity behind a simple interface.

Prefer interfaces like:

inventoryService.createSale(request)
recommendationService.recommend(queryContext)
catalogImporter.importFromCsv(filePath)
reportService.generateRevenueSummary(range)

Avoid splitting code only because smaller files look cleaner. Split when the new module owns a coherent responsibility or hides real complexity.

6. Hide information

Important decisions should have one home. Centralize:

• business rules
• validation rules
• normalization rules
• ranking or scoring weights
• thresholds
• transaction policies
• external API quirks
• provider-specific payload shapes
• prompt templates
• date/time rules
• file-format details

If callers must know internal details to use a feature correctly, redesign the interface.

7. Reduce change amplification

Simulate likely future changes before finalizing a design:

• What if a field is renamed or added?
• What if the data source changes?
• What if a provider is replaced?
• What if the ranking or business rule changes?
• What if the UI adds another view or filter?
• What if localization, permissions, or auditability becomes required?

If the answer requires edits in many unrelated files, improve the boundary.

8. Use tests as design feedback

Target tests where risk exists:

• domain rules
• data normalization
• ranking/scoring
• API response contracts
• authorization or permission boundaries
• database transaction behavior
• integration error handling
• regression bugs
• edge cases

If tests cannot be run or added, report the gap honestly.

9. Refactor with restraint

Refactor when it reduces complexity, not only when code can be rearranged.

Good reasons to refactor:

• duplicated knowledge
• mixed responsibilities
• unclear names
• scattered validation
• hidden dependencies
• large functions/components doing unrelated work
• UI or routes containing domain rules
• persistence details leaking into unrelated layers

Preserve behavior unless the user explicitly asks to change behavior.

10. Communicate tradeoffs

For significant decisions, report:

• chosen design
• alternative considered
• why the chosen design is simpler or safer
• what complexity remains
• tests/checks performed
• risks or follow-up work

Do not claim tests passed unless they actually ran successfully.

Code review rubric

When reviewing a design or implementation, check:

Complexity:
  Does this reduce or increase long-term complexity?
  Are there hidden dependencies?
  Is cognitive load reasonable?

Interfaces:
  Is the public interface simpler than the implementation?
  Are callers protected from internal details?
  Are error cases visible and understandable?

Boundaries:
  Are routes/controllers thin enough?
  Are business rules in the right layer?
  Are database/API/provider details hidden?

Information hiding:
  Is each rule represented in one canonical place?
  Are constants and mappings named and centralized?

Changeability:
  Would likely future changes be localized?
  Are irreversible choices isolated behind interfaces?

Testing:
  Are risky behaviors tested?
  Are edge cases covered or documented?

Pragmatism:
  Is the solution appropriate for the current stage?
  Are hacks isolated, named, and justified when unavoidable?

Final response formats

For implementation or review tasks:

1. What changed or was reviewed
2. Why this design was chosen
3. Complexity reduced or contained
4. Tests/checks run
5. Remaining risks or next recommended step

For planning tasks:

1. Real problem or bottleneck
2. Recommended architecture or workflow
3. Alternatives considered
4. Tradeoffs
5. Concrete next steps

References

Load these only when needed:

• references/boundaries.md for layer ownership and data-flow decisions.
• references/anti-patterns.md for design smells and fixes.
• references/code-review-rubric.md for detailed review criteria.
• references/refactoring-protocol.md for safe refactoring steps.
• references/testing-strategy.md for verification planning.
• references/debugging-protocol.md for root-cause debugging.
• references/final-reporting.md for concise user-facing reports.
• references/deep-design-heuristics.md for deeper complexity, interface, abstraction, and change-amplification analysis.

Use scripts/generate_engineering_review_template.py only when the user asks for a reusable Markdown review template or when producing a review artifact.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: benedictdavon
• Source: benedictdavon/software-design-engineering
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.