Configuration Options
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The configuration system in TDD Guard manages the environment settings, model parameters, and file system paths required to enforce Test-Driven Development principles. It provides a centralized Config class that resolves settings from multiple sources, including explicit options objects, environment variables, and system-level project directories.
The configuration scope encompasses AI model selection (Anthropic API vs. Claude CLI), linter integration, and the management of internal data storage where test results and session modifications are persisted. This ensures that the TDD Guard hooks can operate consistently across different development environments and project structures.
Sources: src/config/Config.ts:25-36, README.md:16-25
Architecture and Data Flow
Configuration resolution follows a specific hierarchy where explicit ConfigOptions provided at runtime take precedence over environment variables, which in turn override internal defaults.
Configuration Resolution Logic
The Config class initializes its properties during construction, resolving the project's data directory and validation client. It specifically handles legacy mapping from MODEL_TYPE to modern validationClient types (api, cli, or sdk).
Sources: src/config/Config.ts:40-48, src/config/Config.ts:121-125, src/config/Config.test.ts:311-325
Core Settings
The following table details the primary configuration options available in the system, including their environment variable counterparts and default values.
| Option | Environment Variable | Default Value | Description |
|---|---|---|---|
modelType | MODEL_TYPE | claude_cli | Specifies the underlying model provider (e.g., anthropic_api). |
validationClient | VALIDATION_CLIENT | sdk | Determines the client used for AI validation (api, cli, or sdk). |
modelVersion | TDD_GUARD_MODEL_VERSION | claude-sonnet-4-0 | The specific version of the Claude model to use. |
anthropicApiKey | TDD_GUARD_ANTHROPIC_API_KEY | undefined | Required when using the api or sdk validation clients. |
linterType | LINTER_TYPE | undefined | Defines the linter to use (e.g., eslint, golangci-lint). |
useSystemClaude | USE_SYSTEM_CLAUDE | false | Whether to use the system-installed Claude CLI. |
Sources: src/config/Config.ts:13-20, src/config/Config.ts:86-118, src/config/Config.test.ts:200-215
Path Management
TDD Guard relies on a specific directory structure under .claude/tdd-guard/data to store session state and validation artifacts.
Directory Resolution
The base directory for data is resolved using the following priority:
- Explicit
projectRootpassed in configuration options. CLAUDE_PROJECT_DIRenvironment variable (must be an absolute path containing the CWD).- A relative path to the current working directory if neither of the above are provided.
Sources: src/config/Config.ts:51-62, src/config/Config.ts:131-155, src/config/Config.test.ts:84-105
Internal File Paths
The Config class exposes getters for specific data files used by the system:
These files store the context captured from Claude Code hooks for the AI validator to process. For example, modifications.json contains the intercepted file changes, while test.json contains the processed output from language-specific reporters.
Sources: src/config/Config.ts:74-84, src/cli/buildContext.test.ts:33-55
Validation Client Mapping
The system supports a mapping from legacy modelType strings to modern ClientType identifiers. This ensures backward compatibility while the project migrates to the VALIDATION_CLIENT standard.
Ignore Patterns
The system allows users to exclude specific files from TDD enforcement via ignore patterns. These patterns are stored in the config.json file within the data directory.
- Default Patterns: If no custom patterns are provided, the system ignores common documentation and configuration files such as
*.md,package.json,tsconfig.json, andcomposer.json. - Custom Patterns: Users can define glob patterns (e.g.,
dist/**,**/*.min.js) to skip validation for specific directories or file suffixes.
Sources: src/guard/GuardManager.test.ts:88-105, src/guard/GuardManager.test.ts:117-140
Conclusion
The TDD Guard configuration system provides a robust framework for managing the intersection of AI models, project environments, and TDD enforcement rules. By utilizing a hierarchical resolution strategy and standardized path management, it enables seamless integration into various development workflows while maintaining the strict data separation required for reliable TDD validation.