---
name: design-principles
description: ASDM workspace design principles — core guidelines for AI-assisted software development
---

# ASDM Design Principles

## 1. Context-Driven Development

AI-assisted development must be grounded in well-defined context. Before writing code, establish:

- **Architecture context**: Service boundaries, communication patterns, deployment topology
- **Data model context**: Entity definitions, relationships, constraints, and data flow
- **API context**: Endpoint specifications, request/response schemas, authentication model
- **Coding style context**: Language conventions, naming rules, preferred patterns

**Why**: Without structured context, AI-generated code drifts from project intent and accumulates inconsistencies.

**How to apply**: Use the ASDM Context Builder toolset to generate and maintain `contexts/index.md` before starting any feature work. Inject context into AI sessions at the start of each development cycle.

## 2. PRD-First Feature Delivery

Every feature begins with a Product Requirements Document (PRD), not a code sketch. The PRD defines:

- User-facing behavior and acceptance criteria
- Task breakdown with clear dependencies
- Execution phases (plan → implement → verify)

**Why**: Starting from PRD ensures AI agents implement verified requirements, not assumed ones. It prevents scope creep and misaligned deliverables.

**How to apply**: Use the ASDM PRD Builder toolset to create structured PRDs. Break features into atomic tasks with explicit completion criteria before invoking code generation.

## 3. Prototype Before Production

Validate UI and interaction design through lightweight prototypes before committing to full-stack implementation:

- Static or mock-data prototypes (Vue/React/HTML) for front-end validation
- No backend, database, or API coupling in prototype phase
- Rapid iteration with disposable code

**Why**: Prototypes catch UX and flow issues early, when changes are cheap. Production code built on validated prototypes has fewer rework cycles.

**How to apply**: Use the ASDM Prototype Builder toolset for initial UI exploration. Only promote validated prototype patterns into the production codebase.

## 4. Microservice Boundary Discipline

Each service owns its data, its API, and its domain logic. Cross-service interaction follows:

- Well-defined API contracts (REST or gRPC)
- No shared databases between services
- Minimal inter-service dependency graphs

**Why**: Tangled service boundaries create deployment coupling, test complexity, and make AI-assisted code generation unreliable at integration points.

**How to apply**: Define service boundaries in the architecture context before generating service code. Keep each microservice self-contained — its own persistence, its own domain model, its own error handling.

## 5. Separation of Concerns in Code Structure

Organize code so that AI agents can reason about one concern at a time:

- **Presentation layer**: Views, components, routing — no business logic
- **Business logic layer**: Services, domain rules — no UI or persistence details
- **Data access layer**: Repositories, persistence — no business rules

**Why**: Mixed concerns confuse AI context injection and make targeted generation or modification unreliable. Clean separation allows partial regeneration without cascading side effects.

**How to apply**: Enforce layer boundaries in project scaffolding. Use ASDM skills (e.g., Spring Boot CRUD, FastAPI CRUD) that respect these layers by default.

## 6. Progressive Enhancement Over Big-Bang Generation

Generate code incrementally and validate each step:

1. Scaffolding and configuration first
2. Domain models and data schemas next
3. API endpoints and business logic
4. UI components and integration

**Why**: Large-batch AI generation produces code that is hard to review, debug, and integrate. Stepwise generation with checkpoints catches errors early and keeps the codebase coherent.

**How to apply**: Align ASDM task breakdown with this progression. Verify each phase (compile, test, lint) before moving to the next. Do not skip scaffolding validation.

## 7. Human-AI Collaboration Protocol

AI agents generate; humans validate and direct. The workflow is:

- **Human defines intent** (PRD, context, acceptance criteria)
- **AI generates implementation** (code, tests, configuration)
- **Human reviews and integrates** (code review, testing, deployment decisions)

**Why**: Unreviewed AI-generated code accumulates subtle defects, security gaps, and architectural drift. Human oversight at integration points is the quality gate.

**How to apply**: Treat every AI-generated artifact as a draft requiring review. Use the ASDM PR pipeline to surface AI work for human inspection before merge.

## 8. Reproducible Workspaces

Every development workspace must be reproducible from its configuration:

- Toolset definitions in `.asdm/` directory
- Context specifications in `contexts/index.md`
- Skill configurations and command mappings in `.codebuddy/`
- Project scaffolding scripts

**Why**: Irreproducible setups lead to inconsistent AI behavior, context loss, and team friction. Reproducibility enables any team member or CI agent to recreate the same development environment.

**How to apply**: Store all ASDM configuration in version-controlled `.asdm/` and `.codebuddy/` directories. Never rely on ad-hoc manual setup or unrecorded context injection.

## 9. Fail Fast, Fail Visible

Prefer early, loud failures over silent degradation:

- Compile errors over runtime surprises
- Test failures over manual detection
- Build pipeline failures over deployment incidents
- Explicit validation over implicit assumptions

**Why**: Silent failures in AI-generated code are especially dangerous — they may look correct but violate domain constraints. Loud failures make problems discoverable and fixable.

**How to apply**: Configure CI pipelines (Jenkins) to run on every PR. Require lint, compile, and test stages. Never suppress or silently handle errors in generated code.

## 10. Minimal Viable Complexity

Choose the simplest approach that satisfies the requirement:

- Prefer standard frameworks over custom implementations
- Prefer existing patterns over novel architectures
- Prefer single-service solutions over distributed systems until scale demands it
- Prefer readable code over clever code

**Why**: Complexity is the enemy of AI-assisted maintenance. Complex code has more failure modes, more context requirements, and higher regeneration cost. Simplicity keeps the codebase approachable for both humans and AI.

**How to apply**: When ASDM skills offer standard patterns (Spring Boot CRUD, Vue component scaffolding), use them. Resist over-engineering prototypes or adding speculative features.