smartconfig/AGENTS.md

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:

fmt.Printf("DEBUG: value is %v\n", value)

Write a test that exposes the issue:

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.