docs: add AI coding agent guidelines

[mdelapenya]

What does this PR do?

Adds a comprehensive AI.md file in the repository root to guide AI coding agents working on the Testcontainers for Go codebase.

Content Overview

1. Repository Overview

   • Monorepo structure (core, modules, examples, docs)
   • Project organization and layout

2. Environment Setup

   • Go 1.24.7 requirement and gvm usage
   • Critical environment setup commands

3. Development Workflow

   • Module development process
   • Git conventions and commit format
   • PR creation guidelines
   • Testing procedures

4. Module Development Best Practices

   • Container struct design (use Container, not module-specific names)
   • Run function pattern (5-step implementation guide)
   • Container options patterns (built-in vs custom)
   • State inspection techniques with strings.CutPrefix
   • Variadic arguments usage
   • Return types (struct not interface)

5. Testing Guidelines

   • How to run tests properly
   • Test patterns to follow
   • Troubleshooting common test failures

6. Common Pitfalls

   • Code anti-patterns to avoid
   • Git workflow mistakes
   • Testing issues

7. Reference Documentation

   • Pointers to detailed docs for deep dives

Why is it important?

• Improves AI collaboration: Provides AI agents with repository-specific context and patterns
• Reduces errors: Documents common pitfalls and best practices learned from real development
• Speeds up onboarding: New AI agents can quickly understand the codebase structure and conventions
• Maintains consistency: Ensures AI-generated code follows established patterns
• Complements existing docs: Provides quick reference without duplicating detailed documentation

Implementation Notes

This document distills knowledge from:

• The module migration experience (all 49 modules migrated to Run API)
• Best practices documented in docs/modules/index.md
• Common patterns observed across the codebase
• Git workflow conventions used in the repository

The AI.md file follows emerging industry standards for AI agent guidance, providing actionable instructions while referencing detailed documentation for deeper context.

Alternatives

The industry is still evolving practices for instructing AI coding agents, but several patterns are emerging:

Current Practices

1. .claude/ directory (Anthropic's approach)

• .claude/commands/ - Custom slash commands
• .claude/settings.json - Project-specific settings
• This is what you're using now and is becoming a standard for Claude Code

2. .github/ directory extensions

• .github/AI_INSTRUCTIONS.md or .github/CONTRIBUTING_AI.md
• Co-located with existing developer docs
• Some teams add AI-specific guidelines to existing CONTRIBUTING.md

3. Root-level files (emerging standards)

Common names being used:

• AI.md or AI_GUIDELINES.md - Generic instructions
• AGENTS.md - Specifically for AI agents
• .cursorrules - Cursor IDE specific
• .aiderignore - Aider specific
• CLAUDE.md - Claude-specific (less common)

4. Inline documentation

• docs/ai/ directory with structured guides
• Tool-specific: docs/claude/, docs/cursor/, etc.

What's Working Well

Most effective patterns:

1. Hybrid approach: Root AI.md + .claude/ for tool-specific features
   /AI.md # High-level guidelines
   /.claude/
   /commands/ # Custom commands
   /settings.json # Tool settings
2. Content structure that works:
   - Architecture overview - "This is a Go monorepo with modules in /modules"
   - Workflow rules - "Always run tests before committing"
   - Code patterns - "Use testcontainers.Run() not GenericContainer()"
   - Anti-patterns - "Don't use interface types as return values"
   - Commit conventions - "Use conventional commits with co-author footer"
   - Testing requirements - "Run make pre-commit test before committing"
3. Reference to existing docs - Don't duplicate, point to:
   See plan.txt for migration patterns
   See docs/modules/index.md for best practices

Industry Momentum

• Anthropic (Claude): .claude/ directory approach
• Cursor: .cursorrules file
• GitHub Copilot: Exploring .github/copilot-instructions.md
• Aider: .aiderignore for exclusions
• OpenAI: No official standard yet

Related issues

• Supports ongoing AI collaboration on the repository
• Complements recent documentation improvements in PR chore(modulegen): use Run function when generating modules #3445

[netlify]

✅ Deploy Preview for testcontainers-go ready!

Name	Link
🔨 Latest commit	a2ad6b0
🔍 Latest deploy log	https://app.netlify.com/projects/testcontainers-go/deploys/68e8005008943e00078edba6
😎 Deploy Preview	https://deploy-preview-3446--testcontainers-go.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[coderabbitai]

Summary by CodeRabbit

• Documentation

  • Added a comprehensive AI Coding Agent Guidelines document covering environment setup, project workflow, module best practices, testing guidance, common pitfalls, and templates. No functional changes to the product.

• Chores

  • Updated change-detection script to exclude the new documentation file from build triggers. No impact on runtime behavior or public APIs.

Walkthrough

Added AI.md — a detailed guide for AI coding agents and contributors covering repo overview, environment setup, development workflow, module/container patterns, testing guidance, common pitfalls, commit/PR templates, and generator usage. Also updated scripts/changed-modules.sh to exclude AI.md from module change detection. No functional or public API changes.

Changes

Cohort / File(s)	Summary of Changes
Documentation: AI guidelines AI.md	New documentation file providing comprehensive guidelines for AI coding agents and contributors: repository overview, Go environment and setup, development workflow, module and Container patterns, Run function and options conventions, testing practices, common pitfalls, commit/PR templates, references, and module generator usage. No code or public API changes.
Build tooling script scripts/changed-modules.sh	Updated exclusion list to add AI.md so the script ignores the new documentation file when determining changed modules. No other logic changes.

Sequence Diagram(s)

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Poem

I hop through lines of guidance, nibbling notes with glee,
Carrots of conventions hang on every tree.
Tests snug in burrows, commits neat and bright,
I thump a happy cadence — docs set the path alight. 🥕🐇

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The title succinctly and accurately describes the key change in the pull request by indicating that AI coding agent guidelines are being added to the documentation and follows common commit message conventions for docs updates.
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.
Description Check	✅ Passed	The pull request description clearly describes the addition of AI.md, summarizing its purpose, content overview, and rationale, which directly relates to the changeset and provides meaningful context for reviewers.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between d0b6154 and ddae986.

📒 Files selected for processing (1)

• AI.md (1 hunks)

🧰 Additional context used

🪛 markdownlint-cli2 (0.18.1)

AI.md

48-48: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (18)

• GitHub Check: lint (modules/registry) / lint: modules/registry
• GitHub Check: lint (modules/redis) / lint: modules/redis
• GitHub Check: lint (modules/k3s) / lint: modules/k3s
• GitHub Check: lint (modules/dockermodelrunner) / lint: modules/dockermodelrunner
• GitHub Check: lint (modules/socat) / lint: modules/socat
• GitHub Check: lint (modules/elasticsearch) / lint: modules/elasticsearch
• GitHub Check: lint (modules/chroma) / lint: modules/chroma
• GitHub Check: lint (modules/minio) / lint: modules/minio
• GitHub Check: lint (modules/mysql) / lint: modules/mysql
• GitHub Check: lint (modules/azure) / lint: modules/azure
• GitHub Check: lint (modules/scylladb) / lint: modules/scylladb
• GitHub Check: lint / lint:
• GitHub Check: lint (modulegen) / lint: modulegen
• GitHub Check: lint (modules/etcd) / lint: modules/etcd
• GitHub Check: lint (modules/dind) / lint: modules/dind
• GitHub Check: lint (modules/pulsar) / lint: modules/pulsar
• GitHub Check: lint (modules/artemis) / lint: modules/artemis
• GitHub Check: Analyze (go)

[coderabbitai]

Actionable comments posted: 1

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 538772d and d2cb4f4.

📒 Files selected for processing (1)

• AI.md (1 hunks)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (17)

• GitHub Check: lint (modules/consul) / lint: modules/consul
• GitHub Check: lint (modules/mariadb) / lint: modules/mariadb
• GitHub Check: lint (examples/nginx) / lint: examples/nginx
• GitHub Check: lint (modules/redis) / lint: modules/redis
• GitHub Check: lint (modules/weaviate) / lint: modules/weaviate
• GitHub Check: lint (modules/nebulagraph) / lint: modules/nebulagraph
• GitHub Check: lint (modules/databend) / lint: modules/databend
• GitHub Check: lint (modules/registry) / lint: modules/registry
• GitHub Check: lint (modules/couchbase) / lint: modules/couchbase
• GitHub Check: lint (modules/aerospike) / lint: modules/aerospike
• GitHub Check: lint (modules/rabbitmq) / lint: modules/rabbitmq
• GitHub Check: lint (modules/k3s) / lint: modules/k3s
• GitHub Check: lint (modules/redpanda) / lint: modules/redpanda
• GitHub Check: lint (modules/elasticsearch) / lint: modules/elasticsearch
• GitHub Check: lint (modules/meilisearch) / lint: modules/meilisearch
• GitHub Check: lint (modules/gcloud) / lint: modules/gcloud
• GitHub Check: Analyze (go)

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (1)

scripts/changed-modules.sh (1)

92-92: LGTM — excluding AI.md is correct. Optional robustness: normalize paths in loop.

To ensure exclusions also match when paths come as "./AI.md" (or similar), strip a leading "./" before checks.

 for file in $modified_files; do
+    # normalize path by stripping an optional leading "./"
+    file="${file#./}"
     # check if the file is in one of the excluded files
     for exclude_file in ${excluded_files[@]}; do
         if [[ $file == $exclude_file ]]; then

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between d2cb4f4 and a2ad6b0.

📒 Files selected for processing (2)

• AI.md (1 hunks)
• scripts/changed-modules.sh (1 hunks)

🚧 Files skipped from review as they are similar to previous changes (1)

• AI.md

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)

• GitHub Check: lint (modules/memcached) / lint: modules/memcached
• GitHub Check: Analyze (go)

[stevenh]

LGTM