295 lines
7.2 KiB
Markdown
295 lines
7.2 KiB
Markdown
# ADR-027: Three-Layer Documentation System
|
|
|
|
**Status**: Accepted | Implemented
|
|
**Date**: 2024-11-01
|
|
**Deciders**: Documentation & Architecture Team
|
|
**Technical Story**: Separating session work from permanent documentation to avoid confusion
|
|
|
|
---
|
|
|
|
## Decision
|
|
|
|
Implementar **three-layer documentation system**: `.coder/` (session), `.claude/` (operational), `docs/` (product).
|
|
|
|
---
|
|
|
|
## Rationale
|
|
|
|
1. **Session Work ≠ Permanent Docs**: Claude Code sessions are temporary, not product docs
|
|
2. **Clear Boundaries**: Different audiences (devs, users, operations)
|
|
3. **Git Structure**: Natural organization via directories
|
|
4. **Maintainability**: Easy to distinguish what's authoritative
|
|
|
|
---
|
|
|
|
## Alternatives Considered
|
|
|
|
### ❌ Single Documentation Folder
|
|
- **Pros**: Simple
|
|
- **Cons**: Session files mixed with product docs, confusion
|
|
|
|
### ❌ Documentation Only (No Session Tracking)
|
|
- **Pros**: Clean product docs
|
|
- **Cons**: No record of how decisions were made
|
|
|
|
### ✅ Three Layers (CHOSEN)
|
|
- Separates concerns, clear boundaries
|
|
|
|
---
|
|
|
|
## Trade-offs
|
|
|
|
**Pros**:
|
|
- ✅ Clear separation of concerns
|
|
- ✅ Session files don't pollute product docs
|
|
- ✅ Different retention/publication policies
|
|
- ✅ Audit trail of decisions
|
|
|
|
**Cons**:
|
|
- ⚠️ More directories to manage
|
|
- ⚠️ Naming conventions required
|
|
- ⚠️ NO cross-layer links allowed (complexity)
|
|
|
|
---
|
|
|
|
## Implementation
|
|
|
|
**Layer 1: Session Files (`.coder/`)**:
|
|
```
|
|
.coder/
|
|
├── 2026-01-10-agent-coordinator-refactor.plan.md
|
|
├── 2026-01-10-agent-coordinator-refactor.done.md
|
|
├── 2026-01-11-bug-analysis.info.md
|
|
├── 2026-01-12-pr-review.review.md
|
|
└── 2026-01-12-backup-recovery-automation.done.md
|
|
```
|
|
|
|
**Naming Convention**: `YYYY-MM-DD-description.{plan|done|info|review}.md`
|
|
|
|
**Content**: Claude Code interaction records, not product documentation.
|
|
|
|
```markdown
|
|
# Agent Coordinator Refactor - COMPLETED
|
|
|
|
**Date**: January 10, 2026
|
|
**Status**: ✅ COMPLETE
|
|
**Task**: Refactor agent coordinator to reduce latency
|
|
|
|
---
|
|
|
|
## What Was Done
|
|
|
|
1. Analyzed current coordinator performance
|
|
2. Identified bottleneck: sequential task assignment
|
|
3. Implemented parallel task dispatch
|
|
4. Benchmarked: 50ms → 15ms latency
|
|
|
|
---
|
|
|
|
## Key Decisions
|
|
|
|
- Use `tokio::spawn` for parallel dispatch
|
|
- Keep single source of truth (still in Arc<RwLock>)
|
|
|
|
## Next Steps
|
|
|
|
(User's choice)
|
|
```
|
|
|
|
**Layer 2: Operational Files (`.claude/`)**:
|
|
```
|
|
.claude/
|
|
├── CLAUDE.md # Project-specific Claude Code instructions
|
|
├── guidelines/
|
|
│ ├── rust.md
|
|
│ ├── nushell.md
|
|
│ └── nickel.md
|
|
├── layout_conventions.md
|
|
├── doc-config.toml
|
|
└── project-settings.json
|
|
```
|
|
|
|
**Content**: Claude Code configuration, guidelines, conventions.
|
|
|
|
```markdown
|
|
# CLAUDE.md - Project Guidelines
|
|
|
|
Senior Rust developer mode. See guidelines/ for language-specific rules.
|
|
|
|
## Mandatory Guidelines
|
|
|
|
@guidelines/rust.md
|
|
@guidelines/nushell.md
|
|
```
|
|
|
|
**Layer 3: Product Documentation (`docs/`)**:
|
|
```
|
|
docs/
|
|
├── README.md # Main documentation index
|
|
├── architecture/
|
|
│ ├── README.md
|
|
│ ├── overview.md
|
|
│ └── design-patterns.md
|
|
├── adrs/
|
|
│ ├── README.md # ADRs index
|
|
│ ├── 0001-cargo-workspace.md
|
|
│ └── ... (all 27 ADRs)
|
|
├── operations/
|
|
│ ├── README.md
|
|
│ ├── deployment.md
|
|
│ └── monitoring.md
|
|
├── api/
|
|
│ ├── README.md
|
|
│ └── endpoints.md
|
|
└── guides/
|
|
├── README.md
|
|
└── getting-started.md
|
|
```
|
|
|
|
**Content**: User-facing, permanent, mdBook-compatible documentation.
|
|
|
|
```markdown
|
|
# VAPORA Architecture Overview
|
|
|
|
This is permanent product documentation.
|
|
|
|
## Core Components
|
|
|
|
- Backend: Axum REST API
|
|
- Frontend: Leptos WASM
|
|
- Database: SurrealDB
|
|
```
|
|
|
|
**Linking Rules**:
|
|
```
|
|
✅ ALLOWED:
|
|
- docs/ → docs/ (internal links)
|
|
- docs/ → external sites
|
|
- .claude/ → .claude/
|
|
- .coder/ → .coder/
|
|
|
|
❌ FORBIDDEN:
|
|
- docs/ → .coder/ (product docs can't reference session files)
|
|
- docs/ → .claude/ (product docs shouldn't reference operational files)
|
|
- .coder/ → docs/ (session files can reference product docs though)
|
|
```
|
|
|
|
**Files and Locations**:
|
|
```rust
|
|
// crates/vapora-backend/src/lib.rs
|
|
//! Product documentation in docs/
|
|
//! Operational guidelines in .claude/guidelines/
|
|
//! Session work in .coder/
|
|
|
|
// Example in code:
|
|
// See: docs/adrs/0002-axum-backend.md (✅ OK: product doc)
|
|
// See: .claude/guidelines/rust.md (✅ OK: within operational layer)
|
|
// See: .coder/2026-01-10-notes.md (❌ WRONG: session file in product context)
|
|
```
|
|
|
|
**Documentation Naming**:
|
|
```
|
|
docs/
|
|
├── README.md ← UPPERCASE (GitHub convention)
|
|
├── guides/
|
|
│ ├── README.md
|
|
│ ├── installation.md ← lowercase kebab-case
|
|
│ ├── deployment-guide.md ← lowercase kebab-case
|
|
│ └── multi-agent-workflows.md
|
|
|
|
.coder/
|
|
├── 2026-01-12-description.done.md ← YYYY-MM-DD-kebab-case.extension
|
|
|
|
.claude/
|
|
├── CLAUDE.md ← Mixed case (project instructions)
|
|
├── guidelines/
|
|
│ ├── rust.md ← lowercase (language-specific)
|
|
│ └── nushell.md
|
|
```
|
|
|
|
**mdBook Configuration**:
|
|
```toml
|
|
# mdbook.toml
|
|
[book]
|
|
title = "VAPORA Documentation"
|
|
authors = ["VAPORA Team"]
|
|
language = "en"
|
|
src = "docs"
|
|
|
|
[build]
|
|
create-missing = true
|
|
|
|
[output.html]
|
|
default-theme = "light"
|
|
```
|
|
|
|
**Key Files**:
|
|
- `.claude/CLAUDE.md` (project instructions)
|
|
- `.claude/guidelines/` (language guidelines)
|
|
- `docs/README.md` (documentation index)
|
|
- `docs/adrs/README.md` (ADRs index)
|
|
- `.coder/` (session files)
|
|
|
|
---
|
|
|
|
## Verification
|
|
|
|
```bash
|
|
# Check for broken doc layer links
|
|
grep -r "\.coder" docs/ 2>/dev/null # Should be empty (❌ if not)
|
|
grep -r "\.claude" docs/ 2>/dev/null # Should be empty (❌ if not)
|
|
|
|
# Verify session files don't pollute docs/
|
|
ls docs/ | grep -E "^[0-9]" # Should be empty (❌ if not)
|
|
|
|
# Check documentation structure
|
|
[ -f docs/README.md ] && echo "✅ docs/README.md exists"
|
|
[ -f .claude/CLAUDE.md ] && echo "✅ .claude/CLAUDE.md exists"
|
|
[ -d .coder ] && echo "✅ .coder directory exists"
|
|
|
|
# Verify naming conventions
|
|
ls .coder/ | grep -v "^[0-9][0-9][0-9][0-9]-" # Check format
|
|
```
|
|
|
|
**Expected Output**:
|
|
- No links from docs/ to .coder/ or .claude/
|
|
- No session files in docs/
|
|
- All documentation layers present
|
|
- Naming conventions followed
|
|
|
|
---
|
|
|
|
## Consequences
|
|
|
|
### Documentation Maintenance
|
|
- Session files: temporary (can be archived/deleted)
|
|
- Operational files: stable (part of Claude Code config)
|
|
- Product docs: permanent (published via mdBook)
|
|
|
|
### Publication
|
|
- Only `docs/` published to users
|
|
- `.claude/` and `.coder/` never published
|
|
- mdBook builds from docs/ only
|
|
|
|
### Collaboration
|
|
- Team knows where to find what
|
|
- No confusion between session work and permanent docs
|
|
- Clear ownership: product docs vs operational
|
|
|
|
### Scaling
|
|
- Add new documents naturally
|
|
- Layer separation doesn't break as project grows
|
|
- mdBook generation automatic
|
|
|
|
---
|
|
|
|
## References
|
|
|
|
- `.claude/layout_conventions.md` (comprehensive layout guide)
|
|
- `.claude/CLAUDE.md` (project-specific guidelines)
|
|
- [mdBook Documentation](https://rust-lang.github.io/mdBook/)
|
|
|
|
---
|
|
|
|
**Related ADRs**: ADR-024 (Service Architecture), All ADRs (documentation)
|