motovaultpro/AI_STRUCTURE.md

You are tasked with creating a new project that follows AI-optimized documentation and structure patterns designed for efficient AI-to-AI code maintenance. This project should be self-describing, context-efficient, and progressively discoverable.
Core Setup Instructions

1. Initialize Project Structure
Create this exact directory structure:
project-root/
├── AI_README.md           # 200-token complete system overview
├── PROJECT_MAP.md         # Navigation and quick reference
├── CONVENTIONS.md         # Project patterns and standards
├── CLAUDE.md             # This file - AI interaction guide
├── CHANGELOG_AI.md       # AI-focused change tracking
├── src/
│   ├── core/             # Stable, critical functionality
│   │   └── README.md     # Core module descriptions
│   ├── features/         # Business logic modules
│   │   └── README.md     # Feature development guide
│   ├── shared/           # Reusable utilities
│   │   └── README.md     # Utility usage patterns
│   └── index.{ts|py}     # Main entry point
├── docs/
│   ├── ARCHITECTURE.md   # System design decisions
│   ├── TROUBLESHOOTING.md # Common issues and solutions
│   ├── dependencies.md    # External dependency documentation
│   └── diagrams/         # Visual architecture representations
├── tests/
│   ├── README.md         # Testing strategy
│   ├── fixtures/         # Shared test data
│   └── examples/         # Usage examples
├── templates/            # Code generation templates
│   └── README.md        # Template usage guide
├── .ai/                 # AI-specific metadata
│   ├── context.json     # Context navigation for AI
│   ├── dependencies.yaml # Module dependency graph
│   └── shortcuts.md     # Quick command reference
└── scripts/
    └── setup.{sh|py}    # Project initialization scripts
2. Create Foundation Files
AI_README.md
markdown# Project Name

## AI Quick Start (50 tokens)
[One paragraph describing what this system does, its primary purpose, and key technologies]

## Navigation Guide
- Start here: PROJECT_MAP.md
- Conventions: CONVENTIONS.md  
- Architecture: docs/ARCHITECTURE.md
- AI Metadata: .ai/context.json

## Critical Context
- [List 3-5 things an AI must always know when working on this codebase]

## Primary Entry Points
- Main application: src/index.{ts|py}
- Core modules: src/core/README.md
- Feature modules: src/features/*/index.{ts|py}
PROJECT_MAP.md
markdown# Project Navigation Map

## System Overview
[2-3 sentences about the system architecture]

## Quick Navigation

### By Task
- **Adding a feature**: Start with templates/ → src/features/
- **Fixing bugs**: TROUBLESHOOTING.md → tests/ → src/
- **Modifying core**: Read CONVENTIONS.md first → src/core/
- **Adding tests**: tests/README.md → tests/examples/

### By Frequency
- **Most changed**: [List top 3 most frequently modified paths]
- **Most critical**: src/core/*
- **Most complex**: [List complex modules needing extra context]

## Module Map
\`\`\`
src/
├── core/
│   ├── config/      # Environment and app configuration
│   ├── database/    # Data layer abstractions
│   ├── logging/     # Centralized logging
│   └── security/    # Auth and security primitives
├── features/
│   └── [feature]/   # Each feature is self-contained
│       ├── index    # Public API
│       ├── service  # Business logic
│       ├── types    # Type definitions
│       └── tests    # Feature tests
└── shared/
    ├── utils/       # Pure utility functions
    └── types/       # Shared type definitions
\`\`\`

## AI Interaction Guide
- **Before modifying**: Read .ai/context.json for the area you're working in
- **When debugging**: Start with src/core/logging
- **When adding features**: Use templates/ for consistent patterns
- **After changes**: Update CHANGELOG_AI.md and .ai/dependencies.yaml
CONVENTIONS.md
markdown# Project Conventions

## Code Style

### Naming Conventions
- **Files**: kebab-case.ts or snake_case.py
- **Classes**: PascalCase with descriptive names
- **Functions**: camelCase (JS/TS) or snake_case (Python), verb_noun pattern
- **Constants**: UPPER_SNAKE_CASE
- **Interfaces/Types**: PascalCase with 'I' prefix for interfaces (optional)

### Self-Documenting Code Principles
1. **Prefer clear naming over comments**
   \`\`\`typescript
   // Bad
   const d = new Date(); // Gets current date
   
   // Good
   const currentDate = new Date();
   \`\`\`

2. **Use type hints as documentation**
   \`\`\`python
   def process_order(
       order_data: OrderDict,
       validate: bool = True
   ) -> Result[Order, OrderError]:
       """Process order. See OrderDict for structure."""
       pass
   \`\`\`

3. **Function names should describe complete behavior**
   \`\`\`typescript
   // Bad: validate(data)
   // Good: validateOrThrow(data)
   // Good: validateAndReturnErrors(data)
   \`\`\`

## Documentation Standards

### Progressive Disclosure Pattern
\`\`\`javascript
/**
 * @ai-summary Handles payment processing
 * @ai-details docs/payments/PROCESSING.md
 * @ai-examples tests/examples/payment-processing.test.js
 * @critical-context PCI compliance required, no card storage
 */
\`\`\`

### Required Annotations
- **Services/Classes**: @ai-summary (one line)
- **Complex functions**: HANDLES, THROWS, SIDE_EFFECTS
- **Security-sensitive code**: SAFETY comment
- **External dependencies**: DEPENDS comment

### When to Comment
ONLY add inline comments for:
- Regulatory/compliance requirements
- Non-obvious business logic
- Performance optimizations (with metrics)
- Security considerations
- Workarounds with issue references

## Structure Patterns

### Feature Module Structure
\`\`\`
features/[feature-name]/
├── index.{ts|py}        # Public API (exports only)
├── service.{ts|py}      # Business logic
├── repository.{ts|py}   # Data access
├── types.{ts|py}        # Type definitions
├── validators.{ts|py}   # Input validation
├── README.md           # Feature documentation
└── __tests__/          # Feature tests
\`\`\`

### Service Class Pattern
\`\`\`typescript
export class FeatureService {
    constructor(
        private repository: FeatureRepository,
        private logger: Logger
    ) {}
    
    // Public methods first, prefixed with action verb
    async createFeature(data: FeatureInput): Promise<Result<Feature>> {
        const validated = this.validateOrFail(data);
        return this.repository.create(validated);
    }
    
    // Private helpers last, prefixed with underscore
    private validateOrFail(data: unknown): FeatureInput {
        // Validation logic
    }
}
\`\`\`

## Testing Standards

### Test Naming
- Test files: [module].test.{ts|py} or test_[module].py
- Test names: test_should_[expected_behavior]_when_[condition]
- Use @ai-coverage to link tests to code

### Test Organization
\`\`\`python
class TestFeatureService:
    """
    @ai-coverage FeatureService
    @ai-fixtures tests/fixtures/features/
    """
    
    def test_should_create_feature_when_data_valid(self):
        # Arrange → Act → Assert pattern
        pass
        
    def test_should_reject_when_missing_required_fields(self):
        pass
\`\`\`

## Git Commit Standards
- Format: "type(scope): description"
- Types: feat, fix, docs, refactor, test, chore
- Include "AI-CONTEXT:" line for significant changes

## Error Handling
- Use Result<T, E> pattern or explicit error types
- Never catch and ignore errors silently
- Log errors with context at catch point
- Throw early, catch late

## Performance Guidelines
- Document Big-O complexity for algorithms
- Add benchmarks for critical paths
- Use caching for expensive computations
- Profile before optimizing
.ai/context.json
json{
  "version": "1.0.0",
  "project_type": "[web-api|cli-tool|library|full-stack-app]",
  "language": "[typescript|python|javascript]",
  "context_budget": {
    "always_load": [
      "AI_README.md",
      "CONVENTIONS.md"
    ],
    "essential_paths": [
      "src/core/",
      "src/index.{ts|py}"
    ],
    "conditional": {
      "if_modifying_auth": [
        "src/features/auth/",
        "docs/auth/",
        "src/core/security/"
      ],
      "if_debugging": [
        "src/core/logging/",
        "TROUBLESHOOTING.md",
        "tests/"
      ],
      "if_adding_feature": [
        "templates/feature/",
        "src/features/README.md",
        "CONVENTIONS.md#structure-patterns"
      ],
      "if_modifying_database": [
        "src/core/database/",
        "migrations/",
        "docs/database/"
      ]
    }
  },
  "common_tasks": {
    "add_endpoint": {
      "template": "templates/endpoint.template",
      "checklist": [
        "Define route in router",
        "Add request/response types",
        "Implement handler",
        "Add validation",
        "Write tests",
        "Update API documentation"
      ],
      "examples": "tests/examples/endpoints/"
    },
    "add_feature": {
      "template": "templates/feature/",
      "checklist": [
        "Create feature folder",
        "Define types",
        "Implement service",
        "Add repository if needed",
        "Write tests",
        "Update dependencies.yaml",
        "Add to feature index"
      ]
    },
    "debug_issue": {
      "start_with": [
        "Check TROUBLESHOOTING.md",
        "Review recent CHANGELOG_AI.md",
        "Check logs in src/core/logging",
        "Run relevant tests"
      ]
    }
  },
  "danger_zones": {
    "src/core/security/": {
      "warning": "Security-critical code",
      "required_review": true,
      "checklist": [
        "Run security tests",
        "Check for credential exposure",
        "Verify input validation"
      ]
    },
    "migrations/": {
      "warning": "Database schema changes",
      "required_review": true,
      "checklist": [
        "Test rollback procedure",
        "Verify data preservation",
        "Check migration order"
      ]
    },
    "src/core/config/": {
      "warning": "System configuration",
      "checklist": [
        "Update .env.example",
        "Check all environments",
        "Verify defaults are safe"
      ]
    }
  },
  "dependencies": {
    "external": {
      "critical": ["framework", "database", "auth-library"],
      "optional": ["monitoring", "analytics"]
    },
    "internal": {
      "most_imported": ["src/core/logger", "src/shared/types"],
      "most_dependent": ["src/core/database", "src/core/config"]
    }
  },
  "testing": {
    "test_command": "npm test | pytest",
    "coverage_threshold": 80,
    "critical_paths": [
      "src/core/security",
      "src/core/database",
      "src/features/auth"
    ]
  },
  "performance": {
    "bottlenecks": [],
    "optimization_notes": [],
    "benchmarks": "tests/benchmarks/"
  }
}
.ai/dependencies.yaml
yaml# Module Dependency Graph
# Format: module -> depends_on, consumed_by, impact_level

version: 1.0.0
last_updated: [DATE]

modules:
  core/config:
    depends_on: []
    consumed_by: ["*"]  # Everything depends on config
    critical: true
    modification_impact: "high - requires full system test"
    test_command: "npm test core/config"
    
  core/database:
    depends_on: ["core/config", "core/logging"]
    consumed_by: ["features/*", "migrations"]
    critical: true
    modification_impact: "high - affects all data operations"
    test_command: "npm test core/database"
    
  core/logging:
    depends_on: ["core/config"]
    consumed_by: ["*"]
    critical: true
    modification_impact: "medium - affects debugging capability"
    test_command: "npm test core/logging"
    
  core/security:
    depends_on: ["core/config", "core/database", "core/logging"]
    consumed_by: ["features/auth", "api/middleware"]
    critical: true
    modification_impact: "critical - security review required"
    test_command: "npm test core/security"
    
  features/[example]:
    depends_on: ["core/*", "shared/utils"]
    consumed_by: ["api/routes/[example]"]
    critical: false
    modification_impact: "low - isolated feature"
    test_command: "npm test features/[example]"

# Dependency rules
rules:
  - "Features cannot depend on other features"
  - "Core modules cannot depend on features"
  - "Shared utilities cannot depend on core or features"
  - "All modules must depend on core/config"

# Import cycles to avoid
forbidden_cycles:
  - ["core/database", "core/security", "core/database"]
  
# High-risk modification paths
high_risk_paths:
  - description: "Authentication flow"
    modules: ["core/security", "features/auth", "api/middleware/auth"]
    test_suite: "npm test:auth:full"
    
  - description: "Data persistence layer"
    modules: ["core/database", "migrations", "features/*/repository"]
    test_suite: "npm test:database:full"
3. Create Template Files
templates/feature/index.template
typescript/**
 * @ai-summary [Feature description in one line]
 * @ai-details docs/features/[feature-name].md
 * @critical-context [Any critical information]
 */

export * from './types';
export * from './service';
export { [FeatureName]Repository } from './repository';
templates/feature/service.template
typescript/**
 * @ai-summary Handles [feature] business logic
 * @ai-examples tests/examples/[feature]/
 */
export class [FeatureName]Service {
    constructor(
        private repository: [FeatureName]Repository,
        private logger: Logger
    ) {}
    
    /**
     * HANDLES: [What it processes]
     * THROWS: [Error types]
     * SIDE_EFFECTS: [External changes]
     */
    async create[FeatureName](
        data: [FeatureName]Input
    ): Promise<Result<[FeatureName], [FeatureName]Error>> {
        // Validate -> Process -> Persist -> Return
        const validated = this.validateOrFail(data);
        const processed = this.processBusinessRules(validated);
        return this.repository.create(processed);
    }
    
    private validateOrFail(data: unknown): [FeatureName]Input {
        // Validation logic
        throw new Error('Not implemented');
    }
    
    private processBusinessRules(data: [FeatureName]Input): [FeatureName]Data {
        // Business logic transformations
        throw new Error('Not implemented');
    }
}
4. Project-Specific Setup Commands
Based on the project type, run these initialization commands:
bash# For TypeScript projects
npm init -y
npm install --save-dev typescript @types/node prettier eslint
npx tsc --init

# For Python projects  
python -m venv venv
pip install black pytest mypy pylint

# Initialize git with proper ignores
git init
echo "node_modules/\nvenv/\n.env\n*.log\n.DS_Store" > .gitignore

# Create initial environment file
echo "# Development Environment Variables\nNODE_ENV=development\nLOG_LEVEL=debug" > .env.example
5. Initial CHANGELOG_AI.md Entry
markdown# AI-Focused Changelog

## [Date] - Project Initialization
**Created**: Initial project structure
**Architecture**: [Chosen architecture pattern]
**Key Technologies**: [List main technologies]
**AI Context**: 
- Project follows AI-optimized documentation patterns
- Self-describing code structure implemented
- Progressive disclosure documentation in place
**Entry Points**: 
- Start with AI_README.md
- Conventions in CONVENTIONS.md
- Navigation via PROJECT_MAP.md
Instructions for Claude Code
When creating a new project with these standards:

Start by asking the user:

Project type (API, CLI tool, web app, library)
Primary language (TypeScript, Python, JavaScript)
Key features needed initially
Any specific frameworks or libraries required


Then systematically:

Create the complete directory structure
Generate all foundation files with project-specific content
Set up the .ai/ metadata directory
Create initial templates based on project type
Initialize version control and package management
Write the first entry in CHANGELOG_AI.md


Customize based on project type:

API: Add OpenAPI specs, route templates, middleware patterns
CLI: Add command templates, argument parsing patterns
Library: Add export patterns, public API documentation
Full-stack: Add frontend/backend separation, API contracts


For each file you create:

Ensure it follows the self-documenting principles
Add appropriate @ai-* annotations
Include type hints/interfaces
Create corresponding test file structure
Update .ai/context.json with new paths


Before completing setup:

Verify all imports resolve correctly
Ensure templates have clear replacement markers
Check that navigation paths in documentation are accurate
Confirm .ai/dependencies.yaml reflects actual structure
Test that the project runs with minimal setup


Final output should include:

Complete file structure
All content for foundation files
Setup instructions in a setup.md
Initial test file examples
A "Getting Started for AI" section in AI_README.md



Remember: The goal is to create a codebase that another AI can understand and modify efficiently with minimal context loading. Every decision should optimize for clarity and discoverability.
Example First Response
When you run this setup, respond with:
I'll create an AI-optimized project structure for your [project type]. This setup will follow AI-to-AI communication patterns for maximum clarity and minimal context usage.

## Project Configuration
- Type: [selected type]
- Language: [selected language]  
- Architecture: [chosen pattern]

## Creating Structure...
[Show the directory tree being created]

## Generating Foundation Files...
[List each file as it's created]

## Project Ready!

### Next Steps for AI Interaction:
1. Read AI_README.md for system overview
2. Check CONVENTIONS.md before making changes
3. Use PROJECT_MAP.md for navigation
4. Refer to .ai/context.json for task-specific guidance

### For Human Developers:
1. Run: [setup command]
2. Configure: Copy .env.example to .env
3. Install: [package manager] install
4. Test: [test command]

The project is now optimized for AI maintenance and collaboration!