cl-victor1 Auto Doc
Automatic documentation maintenance system with three-tier structure. MUST be applied after every code change.
Three-Tier Documentation Structure
Tier 1: Root ARCHITECTURE.md
Location: Project root directory.
Content requirements:
- High-level architecture overview (max 10 lines)
- Links to all subdirectory INDEX.md files
- Update trigger: Any feature, architecture, or structural change
Header declaration:
<!-- AUTO-DOC: Update me when project structure or architecture changes -->
Tier 2: Folder INDEX.md
Location: Every folder containing code files.
Format (max 3 lines for overview):
<!-- AUTO-DOC: Update me when files in this folder change -->
# [FolderName]
[1-3 line architecture description]
## Files
| File | Role | Function |
|------|------|----------|
| example.ts | Core | Main entry point |
Tier 3: File Header Comments
Location: Top of every code file (first 3-5 lines after imports).
Format:
/**
* @input Dependencies this file requires from external sources
* @output What this file provides/exports to other parts of the system
* @position Role and importance in the local architecture
* @auto-doc Update header and folder INDEX.md when this file changes
*/
Language-specific formats:
TypeScript/JavaScript:
/**
* @input { UserService } from './services', { config } from '@/config'
* @output { AuthProvider, useAuth } React context and hook for authentication
* @position Core auth layer, wraps entire app
* @auto-doc Update header and folder INDEX.md when this file changes
*/
Python:
"""
@input: requests, json from stdlib; Config from ./config
@output: APIClient class for external service calls
@position: Network layer abstraction
@auto-doc: Update header and folder INDEX.md when this file changes
"""
Go:
// @input: net/http, encoding/json; config from ./internal/config
// @output: Handler struct, NewHandler(), ServeHTTP()
// @position: HTTP request handler for /api/users
// @auto-doc: Update header and folder INDEX.md when this file changes
Mandatory Update Workflow
After ANY code change, execute in order:
- Update file header - Reflect new input/output/position if changed
- Update folder INDEX.md - Add/remove/modify file entry
- Update root ARCHITECTURE.md - Only if structural change
Quick Reference
| Change Type | Update Header | Update INDEX.md | Update ARCHITECTURE.md |
|---|---|---|---|
| Edit file logic | If I/O changes | If role changes | No |
| Create file | Yes (new) | Yes (add entry) | If new feature |
| Delete file | N/A | Yes (remove) | If structural |
| Move file | Yes (new pos) | Both folders | If structural |
| Rename file | Yes | Yes | If structural |
Example: Creating New File
When creating lib/utils/format.ts:
- Add header to new file:
/**
* @input { date-fns } for date formatting
* @output { formatDate, formatCurrency } utility functions
* @position Shared formatting utilities
* @auto-doc Update header and folder INDEX.md when this file changes
*/
- Update or create
lib/utils/INDEX.md:
<!-- AUTO-DOC: Update me when files in this folder change -->
# Utils
Shared utility functions for formatting, validation, and helpers.
## Files
| File | Role | Function |
|------|------|----------|
| format.ts | Utility | Date and currency formatting |
- Update
ARCHITECTURE.mdiflib/utils/is new.