tdd_ai_workshop_cpp/AGENTS.md

Agentic Coding Standards

This repository follows strict agentic coding practices to ensure high-quality, maintainable C++ implementations.

Zero Defects Policy

All code changes must maintain a zero defects policy:

• Every feature or bug fix must be validated by passing tests before merge
• Code reviews focus on correctness, clarity, and adherence to style guidelines
• No known issues or technical debt should be introduced
• When defects are discovered, they are fixed immediately before proceeding with new work

Test-Driven Development (TDD)

We follow the Red-Green-Refactor cycle strictly. You must invoke ./run_tests.sh in each phase:

1. Red: Write a failing test that describes the desired behavior
2. Green: Write the minimum code necessary to make the test pass
3. Refactor: Improve the code while keeping tests passing

All development must start with a test. The repository includes one intentional failing test as a starting point for TDD workflow.

Test Execution

Run the test suite using:

./run_tests.sh

This script:

• Configures the CMake build
• Compiles the vending machine library and test executable
• Executes all Google Test cases
• Reports results with clear pass/fail status

The test suite must pass entirely before any code is merged.

Code Quality Standards

Testing Framework

• Test Framework: Google Test (gtest) + Google Mock (gmock)
• Coverage: All public API functions must have test coverage
• Organization: Tests are located in test/vending_machine_test.cpp

Code Style

• Language Standard: C++23
• Style Tool: clang-format (configuration in .clang-format)
• Enforcement: All code must pass clang-format validation before commit

Agent Responsibilities

When assisting with code changes, agents must:

1. Respect the zero defects policy — all code must be tested and passing
2. Follow the Red-Green-Refactor workflow — tests first, implementation second
3. Enforce style compliance using clang-format standards
4. Ensure all tests pass before considering work complete
5. Maintain clarity and maintainability in all refactoring activities

Getting Started

1. Read the failing test in test/vending_machine_test.cpp
2. Implement the vending machine interface in include/vending_machine.h and src/ files
3. Run ./run_tests.sh frequently to verify progress
4. Refactor once tests pass to improve code quality
5. Repeat for each new requirement