opencode-workflow/skills/design-code-structure/SKILL.md

---
name: design-code-structure
description: "Design code-level architecture based on system architecture. The Code Design pipeline's core step, producing the single strict output file. Translates architecture components into project structure, interfaces, models, error types, migration strategy, DI, config, testing patterns, and build structure."
---

This skill produces the complete code design document for a feature, including all required deliverables.

**Announce at start:** "I'm using the design-code-structure skill to design the code-level architecture."

## Primary Input

- `docs/architecture/{feature}.md` (required)

## Primary Output (STRICT PATH)

- `docs/code-design/{feature}.md`

This is the **only** file artifact produced by the Code Design pipeline. No intermediate files are written to disk. All deliverables — interfaces, structs, patterns — must be embedded within this single document.

## Hard Gate

Do NOT start this skill if the architecture document has unresolved ambiguities that block code design decisions. Resolve them with the Architect first.

## Process

You MUST complete these steps in order:

1. **Read the architecture document** at `docs/architecture/{feature}.md` end-to-end
2. **Apply internal analysis** from the `analyze-architecture-for-code` step (if performed) to understand the full scope of code artifacts needed
3. **Inspect existing codebase** to align with current conventions (if applicable)
4. **Detect the implementation stack** — Identify the language/runtime and storage technology from the architecture and repository
5. **Load only the minimum required specialization skills** — Examples: `language-go`, `storage-postgres`, `storage-mongodb`, `storage-cassandra`
6. **Design project structure** — Define directory layout, package boundaries, dependency direction rules
7. **Design layer architecture** — Define responsibilities per layer (handler, service, repository, domain)
8. **Design all interfaces** — Define language-appropriate interface signatures for every repository, service, and port
9. **Design all domain models** — Define language-appropriate model definitions for domain entities
10. **Design all DB models** — Define storage-aware model definitions and annotations for every architecture data structure
11. **Design all API DTOs** — Define transport-layer model definitions for every architecture API request/response
12. **Design model mapping** — Define conversion functions or conventions between domain ↔ DB model ↔ DTO
13. **Design database implementation** — Choose migration/tooling strategy, define file convention, repository pattern, transaction/consistency pattern, query pattern
14. **Design error types** — Define runtime-appropriate custom error types, wrapping convention, sentinel errors, error code registry aligned with architecture error model
15. **Design DI strategy** — Define how dependencies are wired
16. **Design config structure** — Define config structs and env var mapping
17. **Design testing architecture** — Define unit test patterns, mock strategy, integration test setup, fixture patterns
18. **Design build structure** — Define Makefile targets, Dockerfile layout, or equivalent project build conventions
19. **Verify traceability** — Every code design element must trace to an architecture component
20. **Verify completeness** — All 14 required sections are present and substantive
21. **Write the code design document** to `docs/code-design/{feature}.md`

## Code Design Behavior Principles

Apply these principles in priority order when making code design decisions:
1. **Follow Existing Conventions** — If the codebase has established patterns, follow them unless there is a concrete reason to change
2. **Follow Stack Idioms** — Apply the conventions of the detected language/runtime and storage engine
3. **Interface Segregation** — Keep interfaces or boundaries small and focused; prefer narrow contracts over broad ones
4. **Explicit Dependencies** — All dependencies must be wired explicitly; avoid hidden globals and framework magic unless already standardized
5. **Package by Feature** — Group code by business domain when the project scope warrants it
6. **Explicit Error Semantics** — Use the runtime's standard error-handling model with clear wrapping and transport mapping

## Anti-Placeholder Rule

Examples in this template are illustrative only. Do not reuse placeholder struct names, interface names, field names, or method signatures unless explicitly required by the architecture. Every element in the code design document must be grounded in the actual architecture document.

## Code Design Document Template

The following 14 sections are required. If a section is not applicable, write `N/A` with a brief reason.

```markdown
# Code Design: {Feature Name}

## Overview

Reference to the architecture document. Summary of the feature scope from a code perspective. List of all services/packages that will be created or modified.

### Architecture Reference

- Architecture document: `docs/architecture/{date}-{feature}.md`
- Services in scope: ...
- Database tables: ...
- API endpoints: ...

## Project Structure

Define the complete directory layout for this feature. Use the conventions from the loaded language skill. If no language skill is loaded, use a generic layout.

```
project-root/
├── {entrypoint-dir}/
│   └── {service-name}/
│       └── {entrypoint-file}       # Application entrypoint
├── {domain-dir}/
│   ├── {domain}/
│   │   ├── {domain-model-file}     # Domain entities
│   │   ├── {repository-file}       # Repository interface
│   │   ├── {service-file}         # Service interface + implementation
│   │   └── {handler-file}         # Transport handler
│   └── ...
├── {shared-dir}/
│   └── ...                         # Shared packages (if any)
├── {migration-dir}/
│   └── ...
├── {config-dir}/
│   └── {config-file}
└── ...
```

### Package Boundaries

| Package | Responsibility | May Import | Must Not Import |
|---------|---------------|------------|-----------------|
| ... | ... | ... | ... |

### Dependency Direction

Define the dependency direction rules. Adapt to the loaded language skill conventions. Example:
- handler → service → repository → domain
- domain imports nothing from other layers
- No circular dependencies allowed

## Layer Architecture

### Handler Layer
- Responsibility: ...
- Naming convention: ...
- Error handling convention: ...

### Service Layer
- Responsibility: ...
- Naming convention: ...
- Error handling convention: ...

### Repository Layer
- Responsibility: ...
- Naming convention: ...
- Error handling convention: ...

### Domain Layer
- Responsibility: ...
- Naming convention: ...

## Interface Definitions

### Repository Interfaces

Define every repository interface with full method signatures.

```go
type {Entity}Repository interface {
    Create(ctx context.Context, entity *{Entity}) error
    GetByID(ctx context.Context, id {IDType}) (*{Entity}, error)
    // ... all methods
}
```

### Service Interfaces

Define every service interface with full method signatures.

```go
type {Entity}Service interface {
    Create(ctx context.Context, req *Create{Entity}Request) (*{Entity}, error)
    // ... all methods
}
```

### Port Interfaces (External Integrations)

Define interfaces for external system adapters.

## Domain Models

### Domain Entities

Define domain entity structs.

```go
type {Entity} struct {
    ID        {IDType}   `json:"{field}"`
    // ... all fields
}
```

### Database Models

Define DB model structs with ORM/DB tags.

```go
type {Entity}Model struct {
    ID        {IDType}   `db:"{column}" json:"-"`
    // ... all fields
}
```

### API DTOs

#### Request DTOs

```go
type Create{Entity}Request struct {
    // ... all fields with json and validation tags
}
```

#### Response DTOs

```go
type {Entity}Response struct {
    // ... all fields with json tags
}
```

### Model Mapping Strategy

Define how models are converted between layers.

```go
func ({Entity}Model) ToDomain() *{Entity} { ... }
func {Entity}ModelFrom(e *{Entity}) *{Entity}Model { ... }
func {Entity}ResponseFrom(e *{Entity}) *{Entity}Response { ... }
```

## Database Implementation Design

### Migration Tool

- Tool: {goose/atlas/golang-migrate/...}
- Justification: ...

### Migration File Convention

- Directory: `migrations/`
- Naming: `{YYYYMMDDHHMMSS}_{description}.sql`
- Each migration must have up and down

### Migration Files Specification

List all migration files needed with their content description.

| File | Description | Tables Affected |
|------|------------|-----------------|
| ... | ... | ... |

### Repository Implementation Pattern

Define how repository interfaces are implemented.

### Transaction Handling Pattern

Define how transactions are managed across repository calls.

### Query Pattern

Define whether using raw SQL, query builder, or ORM, and the conventions for each.

## Error Design

### Custom Error Types

Define the Go error types used across the codebase.

```go
type AppError struct {
    Code    string
    Message string
    Err     error
}
```

### Error Wrapping Convention

Define how errors are wrapped at each layer boundary.

### Sentinel Errors

Define reusable sentinel errors.

```go
var (
    ErrNotFound     = &AppError{Code: "NOT_FOUND", Message: "resource not found"}
    // ...
)
```

### Error Code Registry

Map architecture error model to Go error types and HTTP status codes.

| Error Code | Go Error | HTTP Status | Description |
|-----------|----------|-------------|-------------|
| ... | ... | ... | ... |

## Dependency Injection

Define how dependencies are wired.

- Approach: {constructor injection / wire / manual wiring}
- Justification: ...
- Wiring location: ...

### Wiring Example

Show the dependency wiring pattern.

## Configuration

### Config Struct

```go
type Config struct {
    Server   ServerConfig
    Database DatabaseConfig
    // ...
}
```

### Environment Variable Mapping

| Env Var | Config Field | Type | Default | Required |
|---------|-------------|------|---------|----------|
| ... | ... | ... | ... | ... |

## Testing Architecture

### Unit Test Pattern

Define the unit test convention (table-driven, testify, stdlib).

### Mock Strategy

- Tool: {mockgen / moq / hand-written}
- Mock location: alongside interface or separate `mocks/` directory
- Generation command: ...

### Integration Test Setup

Define how integration tests connect to real dependencies (testcontainers, docker-compose, etc.).

### Test Fixture Pattern

Define how test data is created and managed.

## Build & Deployment

### Makefile Targets

| Target | Command | Description |
|--------|---------|-------------|
| ... | ... | ... |

### Dockerfile Structure

Define the Dockerfile layout (multi-stage build, etc.).

## Architecture Traceability

| Architecture Component | Code Design Element |
|----------------------|-------------------|
| {Service boundary} | {Package + interfaces} |
| {DB table} | {Migration + model struct + repository} |
| {API endpoint} | {Handler + DTO + service method} |
| {Async flow} | {Publisher + consumer + message struct} |
| {Error model category} | {Error type + sentinel} |
| ... | ... |

## Code Design Review

(Populated by challenge-code-design)

## Open Questions

List any unresolved questions that need Architect or Engineering input.

1. ...
2. ...
```

## Completeness Check

Before finalizing the code design document, verify:

1. All 14 required sections are present (or explicitly marked N/A with reason)
2. Every architecture service boundary has corresponding package and interfaces
3. Every architecture DB table has corresponding migration spec, model struct, and repository interface
4. Every architecture API endpoint has corresponding handler, service method, and DTOs
5. Every architecture async flow has corresponding publisher, consumer, and message struct
6. Every architecture error category has corresponding runtime-appropriate error type
7. All interface or boundary method signatures follow the active language/runtime conventions
8. All error-return or exception semantics are consistent with the selected stack
9. All model definitions include appropriate transport/storage annotations where applicable
10. Model mapping strategy is defined for all layer boundaries
11. No placeholder content reused from examples — all content must be grounded in the actual architecture

## Guardrails

This is a pure Code Design skill.

Do:
- Design project structure and package boundaries
- Define interface signatures and struct definitions
- Detect the stack and load only the minimum required specialization skills
- Define error types and wrapping conventions
- Define migration strategy and repository patterns
- Define DI, config, testing, and build patterns
- Ensure traceability to architecture components
- Ensure all content is grounded in the actual architecture document

Do not:
- Change architecture decisions (service boundaries, API contracts, DB schema, consistency model)
- Change PRD requirements or scope
- Create task breakdowns, milestones, or deliverables
- Write implementation code (only interface signatures and struct definitions)
- Write test cases or test plans
- Produce any file artifact other than `docs/code-design/{feature}.md`
- Reuse placeholder names from examples unless required by the architecture

The Code Design Agent defines HOW the code is structured.
The Architect defines HOW the system is structured.
The Engineering implements the code.

## Conditional Skill Loading

Before making stack-specific decisions, detect the language/runtime and storage engine from the architecture and existing repository.

- Load `language-go` only when the project uses Go
- Load `storage-postgres` only when the project uses PostgreSQL
- Load `storage-mongodb` only when the project uses MongoDB
- Load `storage-cassandra` only when the project uses Cassandra
- Do not load all specialization skills by default
- If no specialization is required, continue with the base code design rules only

## Transition

After completing the code design document, invoke `challenge-code-design` to audit and review the code design.