---

name: design-structure description: Design directory structure from layer structure. Derives structure through iterative separation decisions. Use before code generation.

Directory Structure Designer

Overview

Designs directory structure by iteratively deciding how to separate code. Each separation decision involves two choices:

• Axis: Layer or Feature (direction of separation)
• Stage: How far to separate (granularity)

Definitions

Layer

Horizontal axis. Partitions by technical responsibility with defined dependency direction.

Types:

• Feature-bound: Has Code Units per Feature. Example: Entity, InterfaceAdapter
• Cross-feature: Independent of Features. Example: Framework, Config, Middleware

Feature

Vertical axis. Partitions by domain/business concern. Orthogonal to Layer. Example: Task, Project, User, Order

Component

Technical subdivision within a Layer. No dependency direction between Components (parallel). Example: Handler, Repository, Gateway (all within InterfaceAdapter Layer)

Code Unit

Intersection of Layer (or Component) × Feature. The actual code to be organized. Example: TaskEntity, TaskHandler, TaskRepository

CopyFeature-bound Layers:
                          |  Task  | Project | Comment |
--------------------------|--------|---------|---------|
Entity                    |   ●    |    ●    |    ●    |
InterfaceAdapter/Handler  |   ●    |    ●    |    ●    |
InterfaceAdapter/Repository|  ●    |    ●    |    ●    |

Cross-feature Layers:
                          |   DB   |  HTTP   |  Logger |
--------------------------|--------|---------|---------|
Framework                 |   ●    |    ●    |    ●    |

Note:

• Handler and Repository are Components within InterfaceAdapter Layer
• Cross-feature Layers have their own subdivision (not Features)

Axis

Direction of separation: by-layer or by-feature.

• By Layer: Group by technical responsibility (entity.{ext}, handler.{ext}, ...)
• By Feature: Group by domain concept (user.{ext}, project.{ext}, ...)

Stage

Granularity of separation:

Reference:

• Inline
• Functions
• Files
• Packages
• Services

Workflow

1. Read Layer Structure

   • Parse CLAUDE.md for ## Layer Structure section
   • Count Layers, Components (horizontal) and Features (vertical)
   • Identify the (Layer/Component) × Feature matrix

2. Analyze Git History (for existing codebases)

   • Read Git log for scale metrics (total lines, commits/month, contributors)
   • Use metrics to inform Stage selection

3. Derive Separation Decisions

   • For each separation point, decide Axis and Stage
   • Based on Code Unit count, Git metrics, and estimated complexity
   • Do NOT consider current directory structure (derive from requirements only)
   • Do NOT pre-consider language-specific constraints (e.g., circular dependencies)
     • If implementation fails due to constraints, adjust then

4. Write to CLAUDE.md

   • Write designed directory structure to project's CLAUDE.md
   • If differs from current structure, note as proposed change

---

Separation Flow

Each separation decision = Axis (direction) × Stage (granularity)

The (Layer/Component) × Feature matrix is sliced along one axis, then optionally subdivided along the other.

Note: When counting for Axis selection, Components count as separate rows (like Layers).

Step 0: Single File

Everything starts in one file (Stage: inline).

Copymain.{ext}   // all Code Units in one file

Step 1: Initial Separation

Choose Axis based on matrix shape:

Choose Stage based on Code Unit count (see Decision Criteria for details):

Example: Feature axis + files stage (slice by columns)

Copytask.{ext}        // Entity×Task, Handler×Task, Repository×Task
project.{ext}     // Entity×Project, Handler×Project, Repository×Project
comment.{ext}     // ...

Example: Layer axis + files stage (slice by rows)

Copyentity.{ext}      // Entity×Task, Entity×Project, Entity×Comment, ...
handler.{ext}     // Handler×Task, Handler×Project, ...
repository.{ext}  // Repository×Task, Repository×Project, ...

Example: Layer axis + packages stage

Copyentity/
interface_adapter/
  handler/
  repository/

(Internal structure decided in Step 2)

Step 2: Internal Separation

After initial separation, each unit may need further separation using the other Axis.

CRITICAL: Step 2 Stage must be LOWER than Step 1 Stage.

Example of INVALID derivation:

• Step 1: files stage
• Step 2: files stage ← WRONG (must be functions or inline)
• Result: packages ← WRONG (contradicts Step 1)

See references/stages/ for examples of each stage.

Step 3: Extract Cross-feature Layers

Cross-feature Layers are separated independently from Feature-bound Layers.

Layer classification:

CopyFeature-bound:              Cross-feature:
- Entity                    - Framework
- InterfaceAdapter

• Feature-bound Layers share Features → can group by Feature
• Cross-feature Layers have their own subdivision → extracted independently

Result:

Copytask/                      // Feature-bound, grouped by Feature
  entity.{ext}
  handler.{ext}
  repository.{ext}
project/
  ...
framework/                 // Cross-feature, separated independently
  db.{ext}
  http.{ext}

Grouping Rules

Grouping is the inverse of separation.

Can group?

Should group?

---

Decision Criteria

Axis Selection

Stage Selection

By Code Unit count:

By estimated lines per Code Unit:

Principle: Start minimal, grow as needed.

• Default to files stage
• Only use packages when files become unwieldy

Git-based Scale Analysis

For existing codebases (skip for new projects):

When to Separate Further

---

Output Format

Output must be faithful to the analysis results.

• If Step 1 selected files stage, output must be files (not packages)
• Do NOT contradict the derived Stage in the final structure

Write to project's CLAUDE.md:

Copy## Directory Structure

{directory or file tree based on separation decisions}

Copy