Spring Boot 4 Microservices Project - Home Energy Tracker - AI AGENTS.md File (Part 11)

An in-depth exploration of integrating AI coding assistants into a multi-service microservices architecture using custom context configuration files like agents.md. This chapter covers how to guide AI agents to understand project structures, infrastructure dependencies, and architectural rules to generate cleaner, hallucination-free code.

1. Why Do We Need an agents.md File?

With artificial intelligence playing an increasingly massive role in modern software development, developers frequently rely on AI coding assistants (such as GitHub Copilot, Claude, and various IDE plugins) to write, refactor, and debug code. However, standard AI models lack context regarding specific enterprise repositories.

• The Blind Guessing Problem: Without explicit context files, AI tools must guess how a project is structured, what frameworks are used, or how services communicate, frequently leading to incorrect code suggestions.
• Context Overload: In large enterprise systems or multi-service microservices projects, forcing an AI to scan thousands of files degrades response quality, consumes token limits, and increases latency.
• Standardizing AI Behavior: An agents.md file acts as a centralized instruction manual and rulebook that tells the AI agent how to navigate, build, and interact with the specific codebase.

2. Core Mental Model: The AI Rulebook Analogy

Real-Life Analogy: Imagine hiring a brilliant senior developer who has never seen your company's codebase before. If you drop them at a desk without documentation, they will have to read every single file, ask constant questions, and potentially violate internal team conventions.

Now, imagine handing them a onboarding binder (agents.md) that says: "Here is our tech stack, here is how to start our Docker containers, here is our database initialization script, and remember: never put business logic inside REST controllers." The developer becomes instantly productive. An agents.md file does the exact same thing for your AI coding assistant.

3. What is an agents.md File?

An agents.md file is a plain-text Markdown guide placed at the root level of a software project to direct AI behavior.

• Definition: It is a living, evolving document that explicitly outlines project structure, coding standards, toolchains, frameworks, and strict negative constraints (things the AI should never do).
• AI Tool Compatibility:
  • Most standard AI coding agents (such as GitHub Copilot) look for a file named agents.md.
  • Certain specific agents (such as Claude) look for a custom file named claude.md. Developers should always check the documentation of their specific AI agent tooling.

4. Generating the agents.md File in IntelliJ with Copilot

Modern IDE extensions have evolved to automate the creation of these context files by analyzing the workspace.

• Triggering Generation: Upon updating the GitHub Copilot plugin in IntelliJ, the IDE presented a prompt suggesting the generation of an agents.md file.
• Automated Codebase Analysis: Executing the prompt directed an advanced underlying model (such as GPT-5) to scan the entire repository, inspect individual microservices, and map out infrastructure requirements.
• Placement: The resulting file is automatically generated at the top-level root directory of the Home Energy Tracker project, making it instantly discoverable by the AI plugin during subsequent queries.

5. Contents and Structure of the Generated agents.md File

The generated Markdown file serves as an architectural blueprint of the workspace. Below is an overview of what the AI discovers and documents within the file:

Key Sections Found in the Generated File:

1. Infrastructure Dependencies: Lists required external services (e.g., MySQL, Kafka, InfluxDB, Mailpit) that match the local development environment defined in docker-compose.yml.
2. Operational Commands: Explicit instructions on how to spin up, tear down, and manage the local infrastructure stack.
3. Database Initialization: Step-by-step guidelines on how schemas and databases are initialized across services.
4. Service Overview & Architecture Map: A directory-level breakdown of the microservices ecosystem, preventing the AI from needing to crawl thousands of irrelevant source files.

6. Enforcing Architectural Rules and Guardrails

Beyond structural mapping, the agents.md file acts as a governor for design patterns and coding standards.

• Enforcing Separation of Concerns: Engineers can inject explicit architectural rules directly into the markdown file.
  • Example Rule: Controllers must not contain business logic.
• Preventing Anti-Patterns: If an AI agent attempts to write raw SQL queries directly inside a Spring @RestController or service layer where repositories should reside, checking against the agents.md rules prevents the generation.
• Living Document Nature: The file is not static. As the microservices architecture evolves (e.g., adding a new event-driven Kafka consumer or switching caching layers), the agents.md file must be updated to reflect those changes.

7. Combating AI Hallucination

One of the greatest challenges in AI-assisted development is hallucination—where the model invents non-existent methods, outdated library versions, or invalid bean configurations.

• Root Cause: Hallucinations occur when an AI guesses syntax or APIs due to missing context.
• The Solution: Providing a verified, structured agents.md grounds the AI in reality. By explicitly declaring the exact Spring Boot version, Java version, and internal library conventions, the AI agent references real project truths rather than probabilistic hallucinations.
• Engineering Responsibility: As a professional engineer, it is crucial to review the auto-generated agents.md file to verify that commands, paths, and constraints are accurate before trusting the AI to operate on the codebase.

8. Summary and Key Takeaways

• Definition of agents.md: A root-level Markdown guide that instructs AI coding assistants on how to navigate, build, and write code within a specific project.
• Real-World Analogy: Functions identically to an onboarding manual given to a new senior developer, outlining rules, toolchains, and project layout.
• Tooling Variations: While most AI agents look for agents.md, specific tools like Claude may look for claude.md.
• Automated Generation: Modern IDE plugins (like GitHub Copilot in IntelliJ) can analyze codebases automatically to generate initial context files.
• Infrastructure Awareness: Documents project dependencies such as MySQL, Kafka, InfluxDB, and Mailpit, mapping them directly to local Docker configurations.
• Enforcing Guardrails: Allows teams to enforce architectural constraints (e.g., prohibiting business logic inside REST controllers).
• Mitigating Hallucinations: Providing precise structural and technological context drastically reduces AI hallucinations and incorrect syntax generation.
• Living Document: The file must be treated as a living artifact that evolves alongside the microservices codebase.