# Debugging Best Practices for AI Agents

## Test-Driven Debugging

When debugging issues in code, AI agents should follow these practices:

1. **Write Tests, Not Logs**: Instead of adding debug print statements or logging, write unit tests that isolate and demonstrate the bug. This approach:
   - Preserves the debugging work permanently in the codebase
   - Serves as regression tests to prevent the bug from reoccurring
   - Documents the expected behavior clearly
   - Makes the debugging process reproducible

2. **Start Simple**: Write the simplest possible test case that demonstrates the issue. Then progressively add complexity until you've isolated the exact problem.

3. **Test Individual Components**: Break down complex functionality into smaller testable units. For example, if a high-level function is failing, write tests for its component functions to identify where the issue lies.

## Example

Instead of adding debug logging like:
```go
fmt.Printf("DEBUG: value is %v\n", value)
```

Write a test that exposes the issue:
```go
func TestRegexPattern(t *testing.T) {
    re := regexp.MustCompile(`\$\{([^:]+?):(.*?)\}`)
    
    // Test nested case - this will fail with current regex
    input := "${ENV:FOO_${ENV:BAR}}"
    matches := re.FindStringSubmatch(input)
    if len(matches) == 3 {
        t.Logf("Nested pattern matches: resolver=%s, value=%s", matches[1], matches[2])
        // This will show that value is "FOO_${ENV:BAR" which is wrong
    }
}
```

This test remains in the codebase forever, documenting both the bug that was found and serving as a guard against regression.