AI Prompt Engineering
Relevant source files
The following files were used as context for generating this wiki page:
- src/validation/prompts/system-prompt.ts
- src/validation/prompts/rules.ts
- src/validation/prompts/operations/edit.ts
- src/validation/prompts/operations/write.ts
- src/validation/prompts/operations/multi-edit.ts
- src/validation/prompts/response.ts
- src/validation/prompts/file-types.ts
- src/validation/context/context.ts
AI Prompt Engineering in TDD Guard is the systematic design and assembly of specialized instructions that enable an AI model to act as a "TDD Guard." This system translates technical operations—such as file writes, edits, and test results—into a structured context that an LLM can evaluate against strict Test-Driven Development (TDD) principles. The goal is to provide real-time, automated enforcement of the Red-Green-Refactor cycle by intercepting agent tool usage.
The system is modular, combining a foundational system identity, core TDD rules, file-type specific logic, and operation-specific analysis (Edit, Write, MultiEdit). This ensures the AI has a comprehensive understanding of both the developer's intent and the current state of the codebase.
Architecture and Context Assembly
The prompt engineering architecture relies on a dynamic assembly process. The generateDynamicContext function serves as the orchestrator, merging static prompt templates with dynamic data captured from the development environment.
Prompt Composition Flow
The context is built in a specific sequence to ensure the AI prioritizes foundational rules before analyzing specific changes.
The assembly process ensures that the AI's identity and core mission (TDD enforcement) are established before it views the specific code modifications.
Sources: src/validation/context/context.ts:33-51, src/validation/prompts/system-prompt.ts:1-11
Key Prompt Components
| Component | File Path | Description |
|---|---|---|
| System Identity | system-prompt.ts | Defines the AI as a specialized reviewer focused solely on TDD compliance. |
| Core Rules | rules.ts | Outlines the Red-Green-Refactor cycle and identifies core violations like over-implementation. |
| File Rules | file-types.ts | Differentiates logic for test files (`.test.`, `.spec.`) versus implementation files. |
| Operation Logic | operations/ | Specific instructions for analyzing Edit, Write, and MultiEdit tool calls. |
| Response Schema | response.ts | Enforces a strict JSON output format for programmatic blocking/approval. |
Sources: src/validation/prompts/system-prompt.ts, src/validation/prompts/rules.ts, src/validation/prompts/file-types.ts, src/validation/prompts/response.ts
TDD Validation Logic
The prompts are engineered to guide the AI through a specific decision-making tree based on the phase of the TDD cycle.
Red Phase (Test Addition)
For test files, the AI is instructed that adding ONE new test is always allowed, even without prior test output. This is the start of the cycle. Adding multiple tests simultaneously is a primary violation.
Sources: src/validation/prompts/rules.ts:6-10, src/validation/prompts/file-types.ts:7-14
Green Phase (Minimal Implementation)
When reviewing implementation files, the prompt instructs the AI to match the code change to the specific failure message in the test output.
| Failure Message | Allowed Implementation |
|---|---|
| "X is not defined" | Create empty class or function stub only |
| "X is not a constructor" | Create empty class only |
| "X is not a function" | Add method stub only |
| Assertion Error | Implement minimal logic to pass the assertion |
Sources: src/validation/prompts/file-types.ts:24-32, src/validation/prompts/operations/edit.ts:31-40
Refactor Phase
Refactoring is only allowed when relevant tests are passing. The prompts explicitly block refactoring if tests are failing, missing, or irrelevant to the code being changed.
Sources: src/validation/prompts/rules.ts:18-24, src/validation/prompts/file-types.ts:34-45
Operation-Specific Analysis
Edit & MultiEdit Operations
For Edit operations, the AI is tasked with character-by-character comparison of old versus new content. It must distinguish between moving/renaming existing tests and adding genuinely new test blocks. In MultiEdit, the AI must track cumulative changes across multiple sequential edits within a single file.
Sources: src/validation/prompts/operations/edit.ts:11-25, src/validation/prompts/operations/multi-edit.ts:9-16
Write Operations
The instructions for Write operations focus on the intent of the new file. If it is a test file, it should typically contain only one test. If it is an implementation file, it must be justified by an existing failing test.
Sources: src/validation/prompts/operations/write.ts:11-22
Output and Decision Enforcement
The system mandates a strict JSON response format to ensure the tdd-guard CLI can act on the AI's decision.
{
"decision": "block" | null,
"reason": "Clear explanation with actionable next steps"
}
Decision Flow
The "block" decision is triggered by "Multiple Test Addition," "Over-Implementation," "Premature Implementation," or "Refactoring without passing tests."
Sources: src/validation/prompts/response.ts:4-16, src/validation/prompts/rules.ts:26-39
Conclusion
AI Prompt Engineering in this project acts as the "brain" of the validation engine. By providing the LLM with a highly structured environment—defining its persona, the legal transitions of the TDD state machine, and specific heuristics for code diff analysis—the system achieves consistent enforcement of development discipline that would be difficult to capture via static analysis alone.