Skip to content

AGENTS.md

Latest commit

 

History

History
189 lines (135 loc) · 5.37 KB

AGENTS.md

File metadata and controls

189 lines (135 loc) · 5.37 KB
Raw

AI Agent Guidelines for FizzBuzz Enterprise Edition

This document provides guidance for AI coding assistants and autonomous agents working with the FizzBuzz Enterprise Edition codebase.

Overview

FizzBuzz Enterprise Edition is an enterprise-grade FizzBuzz solution using event-driven architecture and LLM-powered divisibility detection. AI agents should understand the system's architecture before making changes.

Architecture Summary

Numbers → Kafka → Fizz/Buzz Services (LLM) → Aggregator → API
  • Event-Driven: All communication happens via Kafka topics
  • Polyglot: TypeScript (services), Go (ingestion), Python (analytics)
  • AI-Powered: Divisibility determined by Claude API calls

Repository Structure

/services/
  fizz-service/        # TypeScript - divisibility by 3
  buzz-service/        # TypeScript - divisibility by 5
  fizzbuzz-aggregator/ # TypeScript - stream join
  api-service/         # TypeScript - GraphQL API
  number-ingestion-service/ # Go - number ingestion

/analytics/
  dbt/                 # dbt models for analytics
  scripts/             # Python analytics scripts

/prompts/              # Versioned LLM prompts (CRITICAL)
/evals/                # Evaluation datasets and results
/mcp-server/           # MCP tool server
/docs/                 # Documentation, ADRs, runbooks
/terraform/            # Infrastructure as code

Critical Guidelines

1. Prompt Modifications

EXTREME CAUTION REQUIRED when modifying files in /prompts/.

  • Always create a new version (e.g., fizz-divisibility-v13.txt)
  • Never modify existing versioned prompts in place
  • Run the full evaluation suite before committing: npm run evals
  • Document changes in the prompt file header
  • See ADR-031 for why this matters

Example of what NOT to do:

# BAD: Modifying existing prompt
# prompts/fizz-divisibility-v12.txt was changed

# GOOD: Create new version
# Created prompts/fizz-divisibility-v13.txt with changes

2. Kafka Topics

Do not create, delete, or rename Kafka topics without explicit user confirmation. Topic changes require:

  • Update to Terraform
  • Update to all consuming services
  • Coordination with data platform team

Existing topics:

  • number-topic - Input numbers
  • fizz-topic - Fizz determination results
  • buzz-topic - Buzz determination results
  • fizzbuzz-topic - Final FizzBuzz results

3. Environment Variables

  • Never hardcode API keys or secrets
  • Use .env.example as the source of truth for required variables
  • When adding new environment variables, update .env.example

4. Testing Requirements

Before suggesting changes are complete:

  • Run npm test for TypeScript services
  • Run go test ./... in Go service
  • Run pytest for Python code
  • Run npm run typecheck for type checking

5. ADR Requirements

For significant architectural changes, create an ADR:

  • Copy docs/adrs/ADR-TEMPLATE.md
  • Use next available number
  • Document context, decision, and consequences

Common Tasks

Adding a New Divisibility Check

If asked to add a new divisor (e.g., "Bazz" for divisibility by 7):

  1. Create new service in /services/bazz-service/
  2. Create new prompt in /prompts/bazz-divisibility-v1.txt
  3. Create new Kafka topic configuration
  4. Update aggregator to join the new topic
  5. Update API schema
  6. Add evaluation dataset in /evals/datasets/
  7. Update documentation
  8. Create ADR documenting the decision

Modifying LLM Behavior

  1. Create new prompt version in /prompts/
  2. Update .env.example with new version
  3. Run evaluations: cd evals && python run_evals.py
  4. Compare accuracy metrics
  5. Document tradeoffs

Adding API Endpoints

  1. Update GraphQL schema in /services/api-service/src/schema/
  2. Add resolver
  3. Add tests
  4. Update API documentation

Working with MCP Server

The MCP server exposes FizzBuzz tools to AI assistants via the Model Context Protocol.

Location: /mcp-server/

Key files:

  • src/tools/ - Tool implementations (fizzbuzz, recent-results, stats)
  • src/api-client.ts - GraphQL client for API service
  • src/config/ - Environment configuration

When modifying:

  1. Tools must validate inputs with Zod schemas
  2. All API calls must be traced with OpenTelemetry
  3. Run tests: cd mcp-server && pnpm test
  4. Test manually with MCP Inspector: pnpm inspect

See ADR-048 for architecture decisions.

Do Not

  • Do not commit to main directly - all changes require PR
  • Do not modify evaluation golden datasets without explicit approval
  • Do not change Kafka consumer group IDs (causes reprocessing)
  • Do not skip DCO sign-off on commits
  • Do not decrease test coverage

Helpful Commands

# Run all TypeScript tests
npm test

# Run Go tests
cd services/number-ingestion-service && go test ./...

# Run Python tests
cd analytics && pytest

# Run linting
npm run lint

# Type check
npm run typecheck

# Run evaluations
cd evals && python run_evals.py

# Generate GraphQL types
npm run codegen --workspace=services/api-service

Contact

If you encounter issues or need clarification:

  • Check existing ADRs in /docs/adrs/
  • Check runbooks in /docs/runbooks/
  • Reference incident retrospectives in /docs/incidents/

Version

This document applies to FizzBuzz Enterprise Edition v4.2.x.

Last updated: 2026-01-31 Maintainer: @fizzbuzz-platform-team