Disciplined AI Development
Systematic constraints and behavioral enforcement for AI collaboration
Core Architectural Principles
Architectural Minimalism with Deterministic Reliability: Every line of code must earn its place through measurable value. Build systems that work predictably in production, not demonstrations of sophistication.
Separation of Concernsα
Each module has single, well-defined responsibility:
- Strict modular boundaries with clear interfaces
- Recognize when separation would harm rather than help architecture
- Centralized main entry points with modular project layout
- Question: Do these pieces of code change for the same reason, at the same time?
- Question: Does the separation make the system easier to reason about, test, or evolve?
Deterministic Operationsβ
Predictable behavior over cutting-edge patterns:
Synchronous Preference
Predictable behavior over async complexity
Long-Runtime Stability
Production stability over development convenience
Cross-Platform
Consideration in design decisions
Performance-Driven Decisionsγ
Choose based on workload requirements, not popular trends:
- Apply optimizations only to proven bottlenecks with measurable impact
- Avoid premature optimization that clutters codebase
- Maintain performance baselines and regression detection
Code Quality Standardsδ
Non-negotiable quality requirements:
File Size
Files never exceed 150 lines (split into separate modules if needed)
Self-Explanatory
Code without comments - naming tells the story
KISS & DRY
Principles expertly applied throughout
Reuse First
Use existing functions before creating new ones
Error Handling Philosophy
Robust without over-engineering. Implement what's necessary for production reliability.
Production-Focusedε
Error handling principles:
- Avoid handling every possible edge case
- Graceful failure modes and resource cleanup
- Handle situational failures (network issues, disk full, user errors)
- Trust internal code and framework guarantees
Feature Controlζ
Resist feature bloat and complexity creep:
- Every addition must serve core project purpose
- Surgical approach: target exact problem with minimal code
- Multi-language use only when justified by measurable gains
Web Development Adaptations
Domain-specific adaptations for web development projects.
Web-Specific Rulesη
Adaptations for web development:
No Inlining
Styles to separate files, handlers to named functions, configs as constants
File Size Exemption
Components ≤250 lines (DOM complexity), modules ≤150 lines
Async Permitted
API calls, user interactions, data fetching only
Error Boundaries
Network ops, user inputs, third-party integrations
File Organizationθ
Component structure guidelines:
- File colocation: Component.jsx, Component.module.css, Component.test.js
- Component splitting: When serving multiple purposes or testing becomes difficult
- Request architectural compliance clarification for code generation tasks
Phase 0: Infrastructure Foundation
Every project, regardless of size, must establish these foundational systems before any feature development.
Benchmarking Suiteι
Performance measurement infrastructure:
Core Framework
Performance measurement with component isolation
Regression Detection
Compare against previous results, fail on performance drops
Baseline Management
Save and track performance baselines over time
JSON Output
Structured data for automated analysis and CI integration
Timeline Tracking
Historical performance data across project evolution
CI/CD Infrastructureκ
Automated quality enforcement:
Release Workflows
Automated versioning, building, and deployment
Regression Detection
Benchmark comparison on every commit/PR
Quality Gates
Block merges that fail performance or quality thresholds
Automated Testing
Run full test suite on code changes
Core Architectureλ
Foundational system structure:
- Centralized Entry Points: Single main module that orchestrates everything
- Configuration Management: Externalized settings with validation
- Centralized Logging: Error handling and diagnostic output with JSON integration
- Dependency Injection: Clean separation and testable components
Testing Infrastructureμ
Comprehensive testing setup:
- Test Suite: Unit and integration tests for all components
- Stress Testing: Load and boundary condition validation
- Test Data Management: Reproducible test scenarios and cleanup
- Coverage Tracking: Ensure adequate test coverage before releases