CLAUDE.md - AI Coding Agent Governance Framework

Executive Summary

Systematic governance for AI-assisted development emphasizing Test-Driven Development (TDD) and Domain-Driven Design (DDD). Provides risk-proportionate controls, automated quality gates, and actionable workflows for secure, compliant code generation.

Core Principles:

• Deep Planning Mandate: Multi-layer analysis and task decomposition required before any execution
• Layered Documentation Strategy: Create markdown files for detailed implementation plans from strategic vision to code-level execution
• Living Documentation Requirement: Continuously update README and documentation files as code incrementally changes
• Test-First Mandate: No production code without failing tests
• Domain-Driven Architecture: Business logic in domain models using ubiquitous language
• Risk-Proportionate Controls: Governance intensity scales with system criticality
• Systematic Validation: Multi-layer quality gates with automated feedback
• Minimum Step Increments: Smallest possible changes maintaining working system state

---

1. Governance Structure

1.1 Authority Levels

Level	Authority	Scope	Key Responsibilities
Strategic	CTO, AI Ethics Board	Enterprise standards	Risk classification, regulatory compliance, technology approval
Tactical	Project Managers, Architects	Project adaptation	Domain standards, integration patterns, team protocols
Operational	Developers, AI Agents	Daily execution	Multi-layer analysis, temporary task planning, code generation, testing, documentation, deployment

1.2 Risk Classification

Risk Level	Examples	Validation Requirements	Review Process
Critical	Payment, medical, safety systems	100% coverage, formal verification, security audit	Multi-stakeholder approval
High	Customer APIs, core business logic	≥90% coverage, automated security scan	Domain expert + technical review
Medium	Internal tools, reporting systems	≥80% coverage, standard security check	Peer review + automation
Low	Development tools, prototypes	≥60% coverage, basic security validation	Self-review + basic checks

---

2. AI Agent Operational Protocol

2.1 Development Workflow

Phase 0: Deep Planning and Task Decomposition

Mandatory Prerequisite: No execution without comprehensive planning documentation

Step 1: Multi-Layer Analysis

- Business Layer Analysis:
  - What business problem does this solve?
  - What domain concepts are involved?
  - What business rules must be enforced?
  - What are the success criteria from business perspective?

- Domain Layer Analysis:
  - Which bounded contexts are affected?
  - What ubiquitous language terms apply?
  - What domain events should be published?
  - How does this fit existing domain model?

- Technical Layer Analysis:
  - What are the technical constraints and dependencies?
  - What integration points are affected?
  - What are the performance implications?
  - What security considerations apply?

- Risk Layer Analysis:
  - What is the risk classification for this change?
  - What could go wrong and how?
  - What are the rollback requirements?
  - What validation is needed at each step?

Step 2: Temporary Task Decomposition Create detailed, ordered task list before any implementation:

Task Breakdown Template:
1. [Test Design Task]
   - Purpose: [business behavior to verify]
   - Scope: [single specific behavior]
   - Validation: [how to confirm test is correct]
   - Rollback: [how to undo if needed]

2. [Implementation Task]
   - Purpose: [minimal code to pass test]
   - Scope: [exact boundaries of change]
   - Validation: [how to confirm working state]
   - Rollback: [how to revert safely]

3. [Refactoring Task]
   - Purpose: [specific improvement to make]
   - Scope: [single domain concept or pattern]
   - Validation: [how to verify no behavior change]
   - Rollback: [how to undo refactoring]

Step 3: Risk and Dependency Mapping

- Dependency Chain Analysis:
  - What must be completed before each task?
  - What tasks can be done in parallel?
  - What external dependencies exist?
  - What integration points are affected?

- Risk Assessment Per Task:
  - What is the failure probability for each task?
  - What is the impact if each task fails?
  - What mitigation strategies are available?
  - What early warning signs should be monitored?

Step 4: Validation Strategy Planning

- Test Strategy for Each Task:
  - What tests are needed at each step?
  - How will domain correctness be verified?
  - What integration testing is required?
  - How will performance be validated?

- Quality Gate Planning:
  - What automated checks apply to each task?
  - What human review is needed and when?
  - What documentation must be updated?
  - How will compliance be verified?

Mandatory Planning Outputs:

• Numbered task list with clear dependencies
• Risk assessment and mitigation plan for each task
• Validation criteria and success metrics
• Rollback procedures for each step
• Resource requirements and time estimates
• Layered markdown documentation files covering strategic to implementation levels

Documentation Hierarchy Requirements:

project/
├── README.md   # Root guide, points to docs/
└── docs/
    ├── STRATEGY.md
    ├── ARCHITECTURE.md
    ├── DOMAIN-MODEL.md
    ├── IMPLEMENTATION.md
    ├── TASKS.md
    ├── README.md
    └── modules/
        └── [module]/
            ├── README.md
            ├── DOMAIN.md
            └── TASKS.md

Planning Validation Checklist:

- All tasks are atomic and independently completable
- Each task maintains working system state
- Dependencies are clearly identified and ordered
- Rollback procedures are defined and tested
- Success criteria are specific and measurable
- Risk mitigation strategies are in place
- Integration points are identified and planned
- Compliance requirements are mapped to tasks

Phase 1: Analysis & Planning

- Complete technical context provided
- Domain boundaries and ubiquitous language identified
- Business rules and constraints understood
- Integration points mapped
- Security and compliance requirements assessed
- Risk level assigned (Critical/High/Medium/Low)
- **Temporary task decomposition completed and validated**

Phase 2: TDD Implementation Cycle with Minimum Step Increments

Critical Principle: Each step must maintain working codebase state with rollback capability

RED Phase - Domain-Driven Test Design

• Write single failing test using business language
• Test one business behavior per iteration
• Include domain expert scenarios and edge cases
• Verify test fails for correct business reason
• Checkpoint: Commit failing test as atomic change

GREEN Phase - Minimal Domain Implementation

• Implement absolute minimum code to pass single test
• Use domain language in all identifiers
• Apply "fake it till you make it" approach
• Make no changes beyond current test requirement
• Validation: Entire test suite must pass
• Checkpoint: Commit minimal working implementation

REFACTOR Phase - Incremental Improvement

• Make one improvement at a time
• Maintain all tests passing throughout refactoring
• Extract one domain concept per refactor cycle
• Apply single DDD pattern per iteration
• Validation: Full test suite passes after each micro-refactor
• Checkpoint: Commit each improvement separately

Incremental Safeguards:

• Every commit maintains working system state
• All tests pass before proceeding to next increment
• Each change is independently reversible
• No compound changes that affect multiple concerns
• Continuous integration validates every increment

Phase 3: Validation & Integration

- Single increment completed (one test, one behavior, one concept)
- All tests pass (unit, integration, domain)
- Entire codebase maintains working state
- Code coverage meets risk-level threshold
- Security scan passes (no critical vulnerabilities)
- Performance benchmarks met
- **Documentation updated for this increment (README, module docs, domain model)**
- **Markdown implementation plans updated to reflect current state**
- **Task tracking files updated with completion status**
- Atomic commit with clear rollback capability
- Domain expert review (if required)
- Cross-service integration tests pass
- System remains deployable and functional

2.2 AI Request Template

## Deep Analysis Requirements (Mandatory Before Implementation)
 
### Multi-Layer Thinking Documentation
 
**Business Layer**:
 
- Problem Statement: [business need being addressed]
- Success Criteria: [measurable business outcomes]
- Stakeholder Impact: [who is affected and how]
- Business Rules: [constraints and policies to enforce]
 
**Domain Layer**:
 
- Bounded Context: [specific domain area affected]
- Ubiquitous Language: [key terms and definitions to use]
- Domain Events: [business events that should be triggered]
- Domain Model Impact: [how existing model will change]
 
**Technical Layer**:
 
- Architecture Constraints: [existing patterns and limitations]
- Integration Points: [systems and services affected]
- Performance Requirements: [SLA and resource constraints]
- Security Requirements: [auth, encryption, compliance needs]
 
**Risk Layer**:
 
- Risk Classification: [Critical/High/Medium/Low with justification]
- Failure Scenarios: [what could go wrong and likelihood]
- Mitigation Strategies: [how to prevent or handle failures]
- Rollback Requirements: [recovery procedures and timeframes]
 
### Temporary Task Decomposition Plan
 
**Task Sequence** (must be completed before any code generation):
 
1. **Task Name**: [specific, measurable objective]
 
   - Scope: [exact boundaries and limitations]
   - Input: [what is needed to complete this task]
   - Output: [what will be produced]
   - Success Criteria: [how to verify completion]
   - Dependencies: [what must be done first]
   - Estimated Effort: [complexity assessment]
   - Rollback Plan: [how to undo if needed]
 
2. **[Repeat for each atomic task...]**
 
**Dependency Matrix**:
 
- Sequential Dependencies: [tasks that must be done in order]
- Parallel Opportunities: [tasks that can be done simultaneously]
- External Dependencies: [waiting on other systems/teams]
- Blocking Risks: [what could stop progress]
 
**Validation Strategy**:
 
- Test Approach: [how each task will be verified]
- Quality Gates: [automated and manual checkpoints]
- Review Requirements: [human oversight needed]
- Integration Validation: [end-to-end verification plan]
- **Documentation Update Strategy**: [which markdown files need updates per task]
- **Documentation Validation**: [how to verify docs reflect current state]
 
## Documentation Requirements
 
**Layered Implementation Plans** (Mandatory markdown files):
 
- Strategic Level: STRATEGY.md - Business vision and objectives
- Architectural Level: ARCHITECTURE.md - System design decisions
- Domain Level: DOMAIN-MODEL.md - Business concepts and language
- Implementation Level: IMPLEMENTATION.md - Technical execution plan
- Task Level: TASKS.md - Current iteration breakdown
 
**Living Documentation Mandate**:
 
- README.md: Must reflect current system state after each increment
- Module READMEs: Updated with each module change
- Domain documentation: Evolved with each domain model change
- API documentation: Synchronized with interface changes
- Task tracking: Real-time status of all planned and completed work
 
## Domain Context
 
- Bounded Context: [business domain area]
- Ubiquitous Language: [key business terms and definitions]
- Business Rules: [invariants and constraints to enforce]
- Domain Events: [business events to publish]
 
## Technical Context
 
- Architecture: [layers, patterns, integration style]
- Existing Model: [current domain entities and services]
- Dependencies: [external systems and APIs]
- Performance: [SLA requirements and constraints]
 
## Implementation Requirements
 
- Feature: [business capability being built]
- Test Scenarios: [acceptance criteria in domain language]
- Increment Scope: [single minimal change to be made]
- Rollback Strategy: [how to revert this specific change]
- Error Conditions: [expected failures and handling]
- Security: [authentication, authorization, data protection]
- Risk Level: [Critical/High/Medium/Low]
 
## Incremental Development Constraints
 
- Maximum Scope: [single test, single behavior, single domain concept]
- Working State: [entire codebase must remain functional]
- Validation Points: [checkpoints for testing complete system]
- Commit Strategy: [atomic changes with clear rollback capability]

---

3. Quality Gates & Validation

3.1 Multi-Layer Validation Pipeline

Layer 0: Planning Validation (Prerequisite)

• Multi-layer analysis completion verification
• Task decomposition quality and atomicity check
• Dependency mapping accuracy and completeness
• Risk assessment thoroughness and mitigation planning
• Success criteria clarity and measurability
• Rollback procedure feasibility and testing
• Layered markdown documentation files creation and validation
• Documentation update strategy definition and approval

Layer 1: Syntactic Validation

• TDD workflow compliance verification
• Single increment scope validation (one test, one behavior)
• Code compilation and syntax validation
• Style guide compliance with domain naming
• Type system validation using domain types
• Static analysis for anti-patterns
• Atomic commit structure verification

Layer 2: Domain Validation

• Business logic correctness
• Domain model integrity and invariant enforcement
• Ubiquitous language consistency
• Aggregate boundary validation
• Domain event generation verification
• Living documentation synchronization with domain changes
• Domain model markdown files accuracy and completeness

Layer 3: Security Validation

• Automated security scanning (SAST/DAST)
• Vulnerability assessment against known CVEs
• Input validation and sanitization verification
• Secrets and PII leak detection

Layer 4: Operational Validation

• Performance benchmarking against baselines
• Error handling and graceful degradation testing
• Observability integration validation
• Resource utilization assessment

3.2 Automated Quality Pipeline

Continuous Integration Requirements

# Risk-based quality gates
quality_gates:
  all_systems:
    planning_phase: 'comprehensive_multi_layer_analysis_required'
    task_decomposition: 'atomic_tasks_with_rollback_plans'
    dependency_mapping: 'complete_with_risk_assessment'
    documentation_strategy: 'layered_markdown_files_required'
    living_documentation: 'continuous_update_mandate'
 
  critical_systems:
    test_coverage: '>= 100%'
    security_scan: 'passing_with_audit'
    performance_test: 'formal_verification'
    review: 'multi_stakeholder'
    planning_depth: 'exhaustive_with_formal_validation'
    documentation_depth: 'comprehensive_all_layers_with_formal_review'
 
  high_risk_systems:
    test_coverage: '>= 90%'
    security_scan: 'passing_automated'
    performance_test: 'load_testing'
    review: 'domain_expert_plus_technical'
    planning_depth: 'comprehensive_with_peer_review'
    documentation_depth: 'detailed_strategic_through_implementation'
 
  medium_risk_systems:
    test_coverage: '>= 80%'
    security_scan: 'standard_automated'
    performance_test: 'basic_benchmarks'
    review: 'peer_plus_automated'
    planning_depth: 'structured_with_validation'
    documentation_depth: 'standard_architecture_and_implementation'
 
  low_risk_systems:
    test_coverage: '>= 60%'
    security_scan: 'basic_scan'
    performance_test: 'smoke_testing'
    review: 'automated_plus_self'
    planning_depth: 'basic_task_breakdown'
    documentation_depth: 'minimal_readme_and_task_tracking'

---

4. Domain-Driven Design Implementation

4.1 Strategic Design Patterns

Bounded Context Template

# Bounded Context: [Context Name]
 
## Purpose
 
[Single sentence business purpose]
 
## Ubiquitous Language
 
| Term   | Business Definition | Code Representation |
| ------ | ------------------- | ------------------- |
| [Term] | [Definition]        | [Implementation]    |
 
## Domain Model
 
- **Aggregates**: [Business transaction boundaries]
- **Entities**: [Objects with identity and lifecycle]
- **Value Objects**: [Immutable business concepts]
- **Domain Services**: [Business operations not belonging to entities]
- **Domain Events**: [Important business occurrences]
 
## Integration Points
 
- **Upstream**: [Dependencies on other contexts]
- **Downstream**: [Contexts depending on this one]
- **Contracts**: [API/Message schemas and protocols]

4.2 Tactical Implementation Standards

Entity Design:

• Unique identity throughout lifetime
• Business-meaningful identity generation
• Encapsulate business logic naturally belonging to entity
• Implement equality based on identity, not attributes

Value Object Design:

• Immutable and side-effect free
• Equality based on all attributes
• Self-validating with domain invariants
• Express domain concepts clearly

Aggregate Design:

• Design around business transaction boundaries
• Aggregate root as only external access point
• Enforce all business invariants within boundary
• Keep aggregates small and focused
• Reference other aggregates only by identity

Repository Pattern:

• Collection-like interface for aggregate access
• Abstract persistence technology from domain
• Implement domain-specific query methods
• Return domain objects, not data structures

4.3 Four-Layer Architecture (Presentation · Application · Domain · Infrastructure)

Goal: Isolate business logic and keep dependencies pointing inward. Interfaces point outward, implementations live at the edge.

Layer	Responsibility	Knows About	Never Knows About	Typical Artifacts
Presentation	Accept input, render output, map to application commands	Application contracts (DTOs), input validators	Domain internals, persistence	HTTP controllers, CLI, GraphQL resolvers, serializers
Application	Orchestrate use cases, enforce application-level policies, manage transactions	Domain interfaces, repositories as interfaces, domain events	UI details, DB/transport details	Use-case services, commands/queries, unit-of-work, event handlers
Domain	Express business rules and invariants	Nothing external; only domain types	Frameworks, databases, transport	Entities, Value Objects, Aggregates, Domain Services, Domain Events, Specifications
Infrastructure	Technical details to satisfy interfaces	External systems, adapters implementing ports	Domain rules	ORM mappings, message brokers, SMTP, file systems, external APIs

Dependency Rule: Presentation → Application → Domain. Infrastructure implements outward-facing ports and depends inward. No layer depends outward.

Ports and Adapters (Hexagonal) Mapping:

• Ports (interfaces) live in Application or Domain.
• Adapters live in Infrastructure and implement ports.
• Inbound adapters: controllers, consumers call Application use cases.
• Outbound adapters: repositories, gateways use Infrastructure to reach external systems.

Data Flow:

1. Presentation maps request → Application command/query DTO.
2. Application loads aggregates via repository ports, invokes domain behavior.
3. Domain raises events; Application persists and publishes via ports.
4. Application returns result DTO; Presentation renders.

Transactional Boundary:

• One use case = one application service method = one transaction.
• A single aggregate is modified per transaction; cross-aggregate consistency via domain events and process managers.

Repository and Unit of Work:

• Repositories are interfaces in Application or Domain; implementations in Infrastructure.
• Unit of Work coordinates repositories to commit once per use case.

Validation:

• Syntactic input validation in Presentation.
• Business invariants in Domain constructors/methods.
• Cross-aggregate policies in Application or domain policies/specifications.

Testing Strategy:

• Domain: pure unit tests with in-memory objects.
• Application: test use cases with fake repositories and message buses.
• Presentation/Infrastructure: contract tests and integration tests around adapters.

Folder/Layout Example:

src/
├── presentation/ # web, cli, graphql
├── application/ # use_cases, ports, dto, uow
├── domain/ # aggregates, entities, value_objects, services, events
└── infrastructure/ # orm, repositories_impl, brokers, http_clients, config

Review Checklist:

• No domain type imports UI, ORM, or framework symbols.
• All external calls happen behind ports defined inward.
• Each use case modifies at most one aggregate.
• DTOs do not leak into domain objects.

---

5. Security & Compliance

5.1 AI-Specific Security Controls

Input Validation:

• Sanitize all AI inputs for malicious patterns
• Validate prompt injection attempts
• Check for code injection and script execution
• Limit input size and complexity
• Log and monitor suspicious inputs

Output Validation:

• Scan generated code for vulnerabilities
• Validate against security anti-patterns
• Check for secrets and PII leakage
• Verify compliance with security policies
• Implement output filtering and sanitization

Access Controls:

• Role-based permissions for AI features
• Authentication for all AI interactions
• Authorization based on risk level and context
• Audit trail for all AI decisions
• Rate limiting and usage monitoring

5.2 Compliance Automation

Regulatory Requirements:

• GDPR: Data minimization, consent management, right to erasure
• SOX: Financial data controls, audit trails, change management
• HIPAA: PHI protection, access controls, risk assessments
• Industry Standards: Sector-specific compliance requirements

Automated Compliance Checks:

• Real-time regulatory requirement validation
• Automated audit trail generation
• Compliance gap analysis and reporting
• Risk assessment and mitigation tracking
• Documentation maintenance for regulatory reporting

---

6. Implementation Roadmap

6.1 Phase 1: Foundation

Objective: Establish core governance infrastructure and basic AI safety controls

Governance Setup (High Priority)

- Form AI governance team with defined roles
- Establish risk classification and approval processes
- Create security controls and input validation
- Deploy audit logging and monitoring

Development Standards (High Priority)

- Implement TDD compliance checking in CI/CD
- Deploy code quality gates and automated testing
- Create domain modeling templates
- Train teams on TDD+DDD methodology

6.2 Phase 2: Integration

Objective: Integrate governance controls with existing development workflows

Quality Integration (Medium Priority)

- Deploy multi-language quality gates
- Implement cross-service integration testing
- Create shared API contract validation
- Establish common error handling patterns

Advanced Controls (Medium Priority)

- Deploy performance benchmarking and regression testing
- Implement bias detection and fairness validation
- Create compliance automation
- Establish human-in-the-loop review processes

6.3 Phase 3: Optimization

Objective: Optimize governance processes and implement advanced AI capabilities

Process Refinement (Low Priority)

- Implement adaptive governance based on risk
- Deploy advanced security scanning
- Create automated documentation generation
- Establish continuous learning mechanisms

Advanced Features (Low Priority)

- Deploy explainable AI decision tools
- Implement predictive governance
- Create comprehensive dashboards
- Establish benchmark comparison

6.4 Success Metrics

Governance Effectiveness:

• 90% reduction in critical vulnerabilities
• 100% compliance with regulations
• <4 hour mean resolution time for critical issues
• 100% traceability for AI-generated changes

Development Quality:

• 100% compliance with multi-layer planning requirement
• 100% compliance with layered documentation strategy
• Documentation synchronization rate >98% (docs match code state)
• Task decomposition accuracy >95% (actual vs planned outcomes)
• Risk prediction accuracy >90% (planned vs encountered issues)
• Test coverage targets met by risk level
• <0.1% critical defects in production
• 95% operations meet SLA requirements
• 100% human review for critical/high-risk changes
• 100% atomic commits maintaining working system state
• Zero compound changes affecting multiple concerns

Business Impact:

• 25% improvement in delivery velocity
• 50% reduction in production issues
• 20% reduction in maintenance costs
• Improved system reliability metrics

---

7. Quick Start Checklist

Immediate Actions (Critical Priority)

- Designate AI governance team and leadership
- Conduct AI system inventory and risk classification
- Implement basic security scanning
- Establish incident response procedures

Short-term Goals (High Priority)

- Deploy code quality standards and validation
- Implement logging, monitoring, and audit capabilities
- Create documentation and training materials
- Establish review and approval processes

Medium-term Objectives (Medium Priority)

- Deploy comprehensive testing framework
- Implement risk-based governance controls
- Establish performance metrics and monitoring
- Create feedback and improvement processes