Documentation Structure: Layered approach from Philosophy to Conventions

[deepracticexs]

Documentation Structure Pattern

Context

We need a clear, standardized way to organize project documentation that helps both humans and AI understand:

• Why we make certain decisions (Philosophy)
• What principles guide our design (Principles)
• How to apply these in practice (Patterns)
• What specific rules to follow (Conventions)

Theoretical Foundation: From Point to Solid

The four-layer documentation structure mirrors a natural evolution from abstract idea to concrete implementation:

Philosophy (Point - 0D)
    ↓ expand
Principles (Line - 1D)
    ↓ extend
Patterns (Framework - 2-3D)
    ↓ fill
Conventions (Solid - filled 3D)

Geometric Dimension Mapping

Philosophy: The Point (Origin)

• A single core idea/belief
• The starting point of all directions
• Example: "AI-Native Development" ← one concept

Principles: The Line (Vector)

• Directions extending from the point
• One-way rules and constraints
• Example: "Apps → Domain → Core" ← a directional arrow

Patterns: The Framework (Skeleton)

• Multiple lines interwoven into structure
• Horizontal and vertical scaffolding
• Example: DDD's "Aggregate-Entity-ValueObject" ← structural relationships

Conventions: The Solid (Filled Entity)

• Every gap in the framework is filled
• Tangible, executable, complete form
• Example: Complete code files with every detail specified

Software Development Lifecycle Mapping

This layering reflects the natural process of building software:

Stage 1: Idea Generation (Philosophy)
  "I want to build an AI-Native development spec tool"
  → A single inspiration
  → The soul of the product

Stage 2: Find Essential Support (Principles)
  "To realize this idea, we must have:"
  - Structured format (for AI understanding)
  - Layered architecture (reduce complexity)
  - Convention over configuration (reduce choices)
  → Identify the core laws that support the idea
  → These laws are inviolable

Stage 3: Build Framework (Patterns)
  "Based on these laws, design:"
  - Monorepo structure (apps/packages/src)
  - Core/Domain separation pattern
  - One-file-one-type pattern
  → Transform laws into reusable templates
  → Developers apply these frameworks for consistency

Stage 4: Mass Production (Conventions)
  "Fill in the details:"
  - File naming: PascalCase.ts
  - Import order: external → internal
  - Commit format: feat: xxx
  → Fill every gap in the framework
  → Form a complete, executable codebase

Why Projects Fail:

• ❌ Only idea, no essential support → castles in the air
• ❌ Have principles, no framework → reinvent the wheel every time
• ❌ Have patterns, no conventions → everyone interprets differently

Successful projects must complete all four stages.

---

Proposed Structure

Based on the Diátaxis Framework and arc42 standards:

docs/
├── README.md                      # Navigation hub
│
├── explanation/                   # Understanding-oriented (Why?)
│   ├── philosophy.md              # Level 1: Design philosophy
│   ├── principles.md              # Level 2: Design principles
│   ├── core-vs-domain.md          # Level 3: Specific patterns
│   └── technical-vs-business.md   # Level 3: Specific patterns
│
├── architecture/                  # Structure-oriented (What?)
│   ├── overview.md                # System overview
│   ├── structure.md               # Directory structure
│   └── decisions/                 # ADR (Architecture Decision Records)
│       └── 004-core-domain-split.md
│
├── guides/                        # Goal-oriented (How to?)
│   ├── getting-started.md
│   ├── creating-core-module.md
│   ├── creating-domain-module.md
│   └── creating-package.md
│
└── reference/                     # Information-oriented (What is?)
    ├── cli.md                     # CLI command reference
    ├── conventions.md             # Coding conventions
    └── glossary.md                # Terminology

Four Documentation Layers: Detailed Positioning

Layer 1: Philosophy - Root Layer of Cognition

"What we believe"

Dimensional Position: Point (0D) - The origin
Core Question: How do we view the world of software development?
Nature: Subjective (idealistic) - Based on beliefs, not proofs
Usage Scenario: Understanding project purpose, making major architectural decisions

# philosophy.md

## Core Beliefs
1. AI-Native Development: Design for AI understanding first
2. Standards Over Flexibility: Strict conventions enable automation
3. Product as Ecosystem: Great tools naturally become reusable
4. Convention Over Configuration: One way to do things

Characteristics:

• Most abstract
• Rarely changes
• Guides all decisions
• No code examples needed

Layer 2: Principles - Bridge Layer from Cognition to Practice

"What rules we follow"

Dimensional Position: Line (1D) - Vectors extending from origin
Core Question: What are the correct architectural principles?
Nature: Objective (materialistic) - Laws of how systems work, verifiable
Usage Scenario: Establishing system structure, defining component boundaries

# principles.md

## Design Principles

### 1. Separation of Concerns
- Technical: How to implement → Core
- Business: What to do → Domain
- Presentation: How to show → Apps

### 2. Dependency Rule
Apps → Domain/Core → Packages (never reverse)

### 3. One File, One Type
Each file exports a single class/interface

Characteristics:

• Derived from philosophy
• Executable rules (can verify right/wrong)
• Clear yes/no criteria
• Component-level constraints (between modules)

Etymology Note: "Principle" from Latin principium (prin- = first, -cipium = beginning). Means "first principle" or "axiomatic truth" - the foundation from which other rules are derived.

Layer 3: Patterns - Practice Framework Layer

"How we apply principles"

Dimensional Position: Framework (2-3D) - Interconnected structure
Core Question: What framework to use for scenario X?
Nature: Unity of subjective and objective - Practical application requiring judgment
Usage Scenario: Choosing design patterns, organizing class structures, deciding code placement

# core-vs-domain.md

## Decision Tree
Is it about "how to implement"?
├─ Yes → src/core/
└─ No → Is it about business rules?
    ├─ Yes → src/domain/
    └─ No → packages/ or apps/

## Examples

### Core Example: TemplateEngine
\`\`\`typescript
export class TemplateEngine {
  render(template: string, data: object): string {
    // Technical implementation
  }
}
\`\`\`

### Domain Example: Order
\`\`\`typescript
export class Order extends AggregateRoot {
  canBeShipped(): boolean {
    // Business rule validation
  }
}
\`\`\`

Characteristics:

• Specific application scenarios
• Requires thinking and judgment
• Concrete code examples with decision trees
• Component-internal rules (within modules)
• Reusable templates

Key Distinction:

• Principles: Rules between components (architecture)
• Patterns: Rules within components (design)

Layer 4: Conventions - Execution Landing Layer

"Exactly how we write code"

Dimensional Position: Solid (filled 3D) - Complete tangible form
Core Question: How to write each step to meet requirements?
Nature: Mechanical rules - Look-up table, no thinking required
Usage Scenario: Writing code, automated tooling checks

# conventions.md

## File Naming
- Classes: \`PascalCase.ts\`
- Utilities: \`camelCase.ts\`
- Constants: \`SCREAMING_SNAKE_CASE.ts\`

## Directory Structure
- One file per class
- \`index.ts\` for public API only
- Use \`~\` for internal imports, \`@\` for external

## Commit Messages
Follow conventional commits:
- \`feat:\` New features
- \`fix:\` Bug fixes
- \`docs:\` Documentation changes

Characteristics:

• Most specific and concrete
• Mechanically checkable (can be enforced by linters)
• Can be automated by tooling
• No interpretation needed

Cognition-to-Practice Transformation Logic

Root Layer (Philosophy)
  ↓ derive
Bridge Layer (Principles) ← constrained by reality
  ↓ apply
Framework Layer (Patterns)
  ↓ standardize
Landing Layer (Conventions)

Core Logic: From "what to think" → "how to do" → "must do this way"

Each layer performs "landing transformation" on the abstraction above it, forming a complete loop from cognition to action.

Benefits

For Humans

1. Clear navigation: Know where to find information
2. Progressive learning: Start abstract, drill down to concrete
3. Maintainability: Each layer has clear purpose
4. Natural evolution: Mirrors how ideas become reality

For AI

1. Precise targeting: AI knows which layer to read for which task
   • Designing new modules → Philosophy + Principles
   • Deciding code placement → Patterns
   • Writing code → Conventions
2. Token efficiency: Load only the necessary abstraction level
3. Generation guidance: Different layers guide different AI tasks
4. Consistency: Standardized structure across projects

Example Usage

AI Prompt in CLAUDE.md

## Documentation Usage Guide

**Task-Based Layer Selection:**
- Understanding design decisions → docs/explanation/philosophy.md + principles.md
- Deciding code placement → docs/explanation/core-vs-domain.md
- Writing code → docs/reference/conventions.md
- Quick start → docs/guides/getting-started.md

**Layer Characteristics:**
- Philosophy: The "point" (origin of all ideas)
- Principles: The "lines" (directional rules from the origin)
- Patterns: The "framework" (structural scaffolding)
- Conventions: The "solid" (filled, complete specification)

Developer Journey

1. New developer → Start with explanation/philosophy.md (understand the point)
2. Need to add feature → Check explanation/core-vs-domain.md (apply patterns)
3. Writing code → Reference reference/conventions.md (follow rules)
4. Specific task → Follow guides/creating-package.md (step-by-step)

Comparison with Standards

Diátaxis Framework

• ✅ Explanation (Understanding) → docs/explanation/
• ✅ How-to Guides (Problem-solving) → docs/guides/
• ✅ Reference (Information) → docs/reference/
• ✅ Tutorial (Learning) → Can add docs/tutorials/ if needed

arc42 Template

• ✅ Section 8 (Concepts) → docs/explanation/
• ✅ Section 9 (Design Decisions) → docs/architecture/decisions/
• ✅ Section 12 (Glossary) → docs/reference/glossary.md

Philosophical Parallels

Marxist Epistemology:

• Worldview (Philosophy) → Methodology (Principles) → Practice (Patterns) → Specific Practice (Conventions)

Aristotle's Four Causes:

• Final Cause (why it exists) → Philosophy
• Formal Cause (what it is) → Principles
• Efficient Cause (how it's made) → Patterns
• Material Cause (what it's made of) → Conventions

Implementation Plan

1. Create docs/ directory structure
2. Write docs/README.md as navigation hub with layer positioning guide
3. Move existing content:
   • Issue Architecture Decision: Use src/ (core) instead of domains/ for NodeSpec #3, Architecture Decision: src/core and src/domain separation #4 → docs/architecture/decisions/
   • CLAUDE.md concepts → docs/explanation/
4. Write core documents with clear layer positioning:
   • explanation/philosophy.md (The Point)
   • explanation/principles.md (The Lines)
   • explanation/core-vs-domain.md (The Framework)
   • reference/conventions.md (The Solid)
5. Update CLAUDE.md to reference new structure with usage guide

References

• Diátaxis Framework
• arc42 Documentation
• C4 Model
• Architecture Decision Records

Related Issues

• Architecture Decision: Use src/ (core) instead of domains/ for NodeSpec #3 - Architecture Decision: domain vs core
• Architecture Decision: src/core and src/domain separation #4 - Architecture Decision: src/core and src/domain separation

Labels

documentation, enhancement

[deepracticexs]

Theoretical foundation complete. Implementation tracked in #6

[deepracticexs]

Theoretical work completed and expanded in #7

[deepracticexs]

Related: #12 now documents the design principles behind NodeSpec's CLI design.

#12 focuses on the foundational principles that guide CLI design, while specific command structures and implementation details will be determined during actual development and documented in feature files.