Skip to main content

TDDAI Claude Code Integration Guide

Overview​

This document details the comprehensive TDDAI (Test-Driven Development AI) integration with Claude Code hooks across the entire LLM Platform ecosystem. The integration provides intelligent TDD enforcement and contextual development assistance for all projects.

Implementation Summary​

Coverage Statistics​

  • Total Projects Configured: 33 projects
  • TypeScript Projects: 18
  • PHP/Drupal Projects: 15
  • Python Projects: 1
  • Docker Services: 2

Project Categories​

1. _CommonNPM TypeScript Projects (13 projects)​

  • llmcli
  • tddai
  • llm-gateway
  • llm-mcp
  • llm-ui
  • secure-project
  • llm-gateway-sdk
  • llm-docs
  • llm-monitoring-stack
  • bfapi
  • bfapiclient
  • bfllm
  • unified-compliance

2. _DrupalSource Modules (12 modules)​

  • llm
  • mcp_registry
  • gov_compliance
  • api_normalizer
  • alternative_services
  • ai_agent_crewai
  • ai_agent_huggingface
  • ai_agent_orchestra
  • ai_agentic_workflows
  • ai_provider_langchain
  • ai_provider_apple
  • recipe_onboarding

3. _DrupalSource Recipes and Themes (3 projects)​

  • Recipes/llm_platform
  • Recipes/secure_drupal
  • Themes/llm_platform_manager

4. Models and LLM-Tools Projects (5 projects)​

  • Models/llm-platform-model
  • Models/tddai-model
  • LLM-Tools/tddai-cursor-agent
  • LLM-Tools/docker-intelligence
  • LLM-Tools/Qdrant

Directory Structure​

Each configured project follows this structure:

project-root/
├── .claude/
│   ├── settings.json
│   └── hooks/
│       ├── tdd-context-injector.[js|cjs]
│       └── tdd-compliance-guardian.[js|cjs]
└── .tddai/
    └── config.yaml

Hook Implementations​

1. TDD Context Injector Hook​

Purpose: Provides contextual TDD reminders and project-specific information when working in Claude Code.

Features:

  • Automatic project type detection (TypeScript, Python, PHP, Docker)
  • Dynamic coverage threshold display
  • Project-specific command suggestions
  • Framework detection (Jest, PHPUnit, pytest)

Example Output:

## TDD Context for TypeScript Project: llmcli

**Project Type**: typescript
**Framework**: jest
**Coverage Target**: 95%

### TDD Requirements:
- ✅ RED: Write failing test first
- ✅ GREEN: Make test pass (minimal code)  
- ✅ REFACTOR: Improve code while keeping tests green
- ✅ Coverage: 95% minimum
- ✅ Follow typescript coding standards

2. TDD Compliance Guardian Hook​

Purpose: Enforces TDD workflow by blocking production code changes without failing tests first.

Features:

  • Monitors code-writing tools (Edit, MultiEdit, Write)
  • Detects test vs production files
  • Configurable enforcement via TDDAI config
  • Project-specific reminders

Enforcement Message:

⚠️  TDD COMPLIANCE CHECK - TypeScript Project: llmcli

You're about to modify production code. Per TDD requirements:

1. ✅ Have you written a FAILING test first?
2. ✅ Is this the minimal code to make the test pass?
3. ✅ Are you in the GREEN or REFACTOR phase?

Configuration Files​

.claude/settings.json​

{
  "hooks": {
    "UserPromptSubmit": {
      "command": "/absolute/path/to/project/.claude/hooks/tdd-context-injector.js"
    },
    "PreToolUse": {
      "command": "/absolute/path/to/project/.claude/hooks/tdd-compliance-guardian.js"
    }
  }
}

.tddai/config.yaml​

project: 
  name: project-name
  type: typescript|python|drupal-module|drupal-recipe|drupal-theme|docker-service
  root: /absolute/path/to/project

testing: 
  framework: jest|phpunit|pytest|docker-test
  coverageThreshold: 80-95
  strictMode: false
  testPatterns: [
    "**/*.test.ts",
    "**/*.spec.ts",
    "__tests__/**/*.ts",
    "tests/**/*.php",
    "tests/**/*.py"
  ]
  sourcePatterns: [
    "src/**/*.ts",
    "src/**/*.php",
    "src/**/*.py",
    "!src/**/*.test.ts",
    "!src/**/*.spec.ts"
  ]

ai: 
  enabled: true
  providers: 
    primary: ollama
    fallbacks: [
      anthropic,
      openai
    ]

integrations: 
  claudeCode: true
  gitHooks: true
  ide: [
    cursor,
    vscode
  ]

quality: 
  enforcePhases: false
  autoFix: true
  generateMissingTests: true

Special Handling​

ES Module Projects​

Projects with "type": "module" in package.json automatically have their hooks renamed to .cjs files to ensure CommonJS compatibility.

Multi-Language Support​

The hooks automatically detect project type based on:

  • package.json → TypeScript/JavaScript
  • requirements.txt or .py files → Python
  • docker-compose.yml → Docker service
  • .info.yml → Drupal module/theme

Coverage Thresholds by Type​

  • TypeScript projects: 95%
  • Python projects: 90%
  • PHP/Drupal projects: 80-95%
  • Docker services: 80%

Setup Commands​

Batch Setup Script​

# Setup for all TypeScript projects
for project in _CommonNPM/*; do
  mkdir -p "$project/.claude/hooks"
  # Create settings.json and hooks...
done

# Setup for all Drupal modules
for module in _DrupalSource/Modules/*; do
  mkdir -p "$module/.claude/hooks"
  # Create settings.json and hooks...
done

Testing the Integration​

Verify Hook Installation​

# Test context injector
cd /path/to/project
node .claude/hooks/tdd-context-injector.js

# For ES modules
node .claude/hooks/tdd-context-injector.cjs

Expected Behaviors​

  1. Opening a project in Claude Code:

    • TDD context automatically appears
    • Project-specific information displayed

  2. Attempting to edit production code:

    • Guardian hook triggers warning
    • Must confirm TDD compliance

  3. Editing test files:

    • No blocking occurs
    • Normal editing allowed

Troubleshooting​

Common Issues​

  1. "require is not defined" error

    • Solution: Rename hooks to .cjs for ES module projects

  2. Hook not triggering

    • Verify absolute paths in settings.json
    • Check file permissions (hooks must be executable)

  3. YAML parsing errors

    • Ensure proper YAML syntax in config files
    • No tabs, only spaces for indentation

Debug Commands​

# Check hook permissions
ls -la .claude/hooks/

# Test hook execution
node .claude/hooks/tdd-context-injector.js

# Verify Claude settings
cat .claude/settings.json | jq .

Benefits​

  1. Enforced TDD Workflow: Prevents code-first development patterns
  2. Contextual Assistance: Project-specific reminders and commands
  3. Quality Gates: Coverage thresholds visible at all times
  4. Multi-Language Support: Works across entire tech stack
  5. Seamless Integration: No manual activation required

Future Enhancements​

  1. Dynamic Coverage Analysis: Real-time coverage display in context
  2. Test Generation Suggestions: AI-powered test stubs
  3. Workflow Analytics: Track TDD compliance over time
  4. Team Synchronization: Shared TDD configurations
  5. IDE Integration: Beyond Claude Code to VS Code, Cursor

Maintenance​

Updating Hooks​

# Update hook logic
vim .claude/hooks/tdd-context-injector.js

# Test changes
node .claude/hooks/tdd-context-injector.js

# Commit and propagate
git add .claude/
git commit -m "Update TDD hooks"

Adding New Projects​

  1. Create .claude/ directory structure
  2. Copy hook templates
  3. Update paths in settings.json
  4. Create .tddai/config.yaml
  5. Test integration

Conclusion​

The TDDAI Claude Code integration provides comprehensive TDD enforcement across the entire LLM Platform ecosystem. With 33 projects configured and intelligent multi-language support, developers receive consistent, contextual guidance to maintain high code quality standards through proper test-driven development practices.