Design Synthesis — Claude Code rule: requirements analysis before architecture
design-synthesis is a rule for analyzing gathered requirements before writing a design document. It uses generalization, build-or-adopt, and simplification to set the solution's scope.
MIT ★ 3,774 updated 2026-10-22
.claude/rules/design-synthesis.mdWhat design-synthesis does
After discovery, before writing the design document, examine requirements through three filters. Design Synthesis offers a concrete process to avoid unnecessary layers and choose the right abstraction level.
First lens: generalization. When multiple requirements are variations of one problem, design a general solution that covers all of them. Keep the implementation narrow to current needs, but make the interface flexible. Second lens: build or adopt. For each major component, ask if the problem is already solved. Look for standards, proven libraries, or platform capabilities. If you adopt, verify it is maintained, compatible with your stack, and meets your non-functional requirements. If you build, document why existing solutions do not fit.
Third lens: simplification. Remove components added "just in case." Flatten abstraction layers that have only one implementation and no clear successor. Prefer a few cohesive pieces over many small ones. The right design is the smallest one that satisfies all requirements and stays extensible at the interface.
What it helps with
- pick the right scope for architecture that matches current requirements
- balance between reuse and overengineering
- decide what to generalize and what to leave specific
- determine whether to build a component or adopt an existing solution
Example prompts for the agent
- Apply the three lenses to requirements before sketching the system architecture
- Ask the agent: is there a standard solution for this component, or do we need to build it?
- Check the design for abstraction layers that have only one implementation
How to install design-synthesis
Manually: put the files in place
.claude/rules/design-synthesis.mdThe paths frontmatter field limits the files
AGENTS.md
Codex reads AGENTS.md: paste the rule text there
Manually: put the files in place
.cursor/rules/design-synthesis.mdcFrontmatter: description, globs, alwaysApply
Manually: put the files in place
.github/instructions/design-synthesis.instructions.mdThe applyTo field sets which files it applies to
Manually: put the files in place
.devin/rules/design-synthesis.mdManually: put the files in place
.clinerules/design-synthesis.mdStep by step, with commands for each platform: AGENTS.md vs CLAUDE.md: what they are and which one to use
Questions about design-synthesis
How do I install Design Synthesis in Claude Code?
Create a file .claude/rules/design-synthesis.md at the project root and add the rule content. Claude Code will apply it automatically on the next session.
What does this rule do?
It provides a structured approach to analyzing requirements before design. Three lenses—generalization, build vs. adopt, and simplification—guide you toward a design that is neither overbuilt nor underspecified, and remains extensible where it matters.
When should I apply Design Synthesis?
After gathering requirements and before writing the design document. The process requires the full picture and cannot be parallelized.
Source text
design-synthesis.md · MIT
# Design Synthesis After discovery and before writing the design document, apply these three lenses to the collected findings. This step requires the full picture — do not parallelize. ## 1. Generalization Look across all requirements as a group. Identify cases where multiple requirements are variations of the same underlying problem. - If feature A is a special case of a more general capability X, design X with an interface that naturally supports A (and potentially B, C later) - Keep the implementation scope to what the current requirements demand — generalize the interface, not the implementation - Record identified generalizations in `research.md` under Design Decisions ## 2. Build vs. Adopt For each major component in the emerging design, ask: is this problem already solved? - Search for established standards (RFCs, protocols), battle-tested libraries, or platform-native capabilities that address the requirement - Prefer adopting existing solutions over building custom ones when they fit the requirements without significant adaptation - If adopting: verify the solution is actively maintained, compatible with the project's stack (check steering), and meets non-functional requirements - If building: document why existing solutions were rejected (capture in `research.md`) ## 3. Simplification For each component and abstraction layer in the emerging design, ask: is this necessary? - Remove components that exist "just in case" or for hypothetical future requirements not in the current spec - Flatten unnecessary abstraction layers — if an interface has only one implementation with no foreseeable second, it may not need the indirection - Prefer fewer, cohesive components over many fine-grained ones - The right design is the smallest one that satisfies all requirements and remains extensible at the interface level
© gotalab · MIT · gotalab/cc-sdd