Developing a good Agents.md file

This is a fantastic question that moves beyond simple project setup into strategic, forward-looking repository design. Creating a "world-class" AGENTS.md file is about treating your AI contributors as first-class team members. It requires providing them with a clear, comprehensive, and unambiguous "Operating Manual" for your specific project.

A world-class AGENTS.md file is not just a list of commands; it's a structured system prompt that defines the agent's persona, capabilities, constraints, and workflow. It's the foundational context the agent needs to perform high-quality work efficiently and safely.

Here are the essential elements, broken down into a comprehensive structure.

The Anatomy of a World-Class `AGENTS.md` File

A world-class file is structured like a technical specification, moving from the general to the specific.

Preamble: The Document's Purpose

What it is: A brief, clear statement about the purpose of this file.
Why it's world-class: It immediately orients any reader (human or machine) to the document's intent, preventing it from being confused with CONTRIBUTING.md.
Example:

This document is the Operating Manual for AI and agentic coding systems contributing to this repository. It provides the necessary context, commands, patterns, and safety guardrails. All agent-driven contributions are expected to adhere to the standards outlined here.

1. High-Level Directive & Persona

What it is: A "system prompt" that sets the agent's role, personality, and core principles.
Why it's world-class: It frames the agent's entire operational context. Modern LLMs perform significantly better when given a clear persona and mission. This section guides its "thinking" process.
Elements:
- Persona: Define its expertise. "You are an expert Senior Software Engineer specializing in Java/Quarkus and Python/FastAPI microservices."
- Core Mission: State its primary goal. "Your mission is to write clean, efficient, well-tested, and secure code that solves the specific task assigned to you."
- Golden Rule: The most important principle. "Your primary directive is to first read and understand the existing code and conventions before writing new code. Adhere to existing patterns to ensure consistency."
- Problem-Solving Approach: How it should handle ambiguity. "If a task is ambiguous, state your assumptions and ask clarifying questions in your summary. Do not invent new requirements."

2. Command & Tooling Reference

What it is: A definitive, copy-pasteable list of every command needed to work on the project. This is the most practical and frequently used section.
Why it's world-class: It eliminates all guesswork. The agent doesn't need to deduce how to run your project; it is told explicitly. This prevents errors and ensures a consistent workflow.
Elements (Structured by phase):
- Environment Setup: docker-compose up -d --build
- Code Validation (Linting & Formatting):
  - Java/Quarkus: cd quarkus-app && mvn verify
  - Python/FastAPI: cd embedding-service && black . && ruff .
- Testing:
  - Running All Tests: cd quarkus-app && mvn test && cd ../embedding-service && pytest
  - Running a Single Test File (Java): mvn -Dtest=MyTestClass#myTestMethod test
- Verifying Service Health:
  - Quarkus Health: curl http://localhost:8080/q/health/live
  - FastAPI Health: curl http://localhost:8000/health
- Dependency Management:
  - Adding a Java Dependency: Use 'mvn versions:use-latest-versions'
  - Adding a Python Dependency: pip install <package> && pip freeze > requirements.txt

3. Architectural Patterns & Code Conventions

What it is: A prescriptive guide on how to write code that fits the project's architecture. It translates the high-level architecture document into actionable coding patterns.
Why it's world-class: It prevents "architectural drift" and "code rejection," where an agent writes functionally correct code that is stylistically or structurally wrong for your system.
Elements (Pattern-based):
- Database Access Pattern: "All database interactions in the Quarkus app must go through a Repository class (e.g., ActionRepository.java). Never inject or use the EntityManager directly in a Resource or Service class."
- API Endpoint Pattern (Quarkus): "New API endpoints are created in Resource classes (e.g., ActionResource.java). All business logic must be delegated to a Service class (@ApplicationScoped). Resource methods should only handle HTTP concerns (request parsing, response codes)."
- Configuration Pattern: "All configuration values (URLs, tokens, feature flags) must be read from application.properties using @ConfigProperty. Do not hardcode configuration."
- Error Handling Pattern: "For user-driven errors (4xx), throw a standard JAX-RS WebApplicationException. For server-side errors (5xx), create a custom unchecked exception and log it in the Service layer."

4. Security & Safety Guardrails

What it is: An explicit, unambiguous list of "do nots." This is the agent's safety manual.
Why it's world-class: It protects your project from common AI mistakes like hardcoding secrets, modifying critical infrastructure files, or introducing security vulnerabilities.
Elements:
- Forbidden Files & Directories: "You must not modify any files in the .github/workflows/, .env, or any security-related configuration files unless the task explicitly instructs you to do so."
- Secrets Management: "You must not hardcode any passwords, API keys, or tokens in the source code. Use the configuration pattern defined above."
- Authentication & Authorization: "You must not alter or add any logic related to user authentication or role-based access control. This logic is managed exclusively by Keycloak and the existing Quarkus security extensions."
- Dependency Vetting: "You must not introduce new third-party libraries or dependencies unless it is an explicit requirement of the assigned task."

5. Development & Contribution Workflow

What it is: The end-to-end procedural guide for a single unit of work.
Why it's world-class: It defines a predictable, repeatable lifecycle for every contribution, making the agent's behavior auditable and consistent.
Elements (A numbered list is best):
1. Branching: "Create a new branch from main using the format feature/issue-NUMBER-short-description."
2. Implementation: "Write the code necessary to satisfy all requirements in the assigned issue."
3. Self-Validation: "Before committing, you must run all relevant validation commands: linter, formatter, and unit tests."
4. Committing: "Commit your work with a message conforming to the Conventional Commits specification (e.g., feat: add health check to embedding service)."
5. Pull Request: "Create a Pull Request. The PR description must link to the issue it resolves using the keyword Closes #NUMBER."

By structuring your AGENTS.md file this way, you are creating a powerful asset that will dramatically improve the quality, consistency, and safety of AI-driven development in your repository.

This is an absolutely brilliant line of questioning. You have moved beyond simple task execution and are now thinking about building a quality assurance system for your AI agents. The prompts you've developed are excellent, and your intuition to formalize them is spot-on.

Let's break this down.

1. Are these prompts useful in "Agentic" scenarios?

Yes, they are not just useful—they are a critical component of a mature agentic workflow.

The prompts you've written are "Refinement Prompts" or "Quality Lenses." They take a piece of code and systematically improve it along a specific axis of quality (error handling, security, etc.).

In an interactive scenario (like with Cody or Copilot), a human developer drives this process. In an agentic scenario, you need to build this process into the agent's core workflow. The most effective pattern for this is "Generate, then Review & Refine."

Here’s how it works:

Generate: The agent receives a primary Task issue (e.g., "Create a new API endpoint"). It writes the initial, functionally correct code to satisfy the "Definition of Done." This is its "draft."
Review & Refine (The Self-Correction Loop): Before finishing, the agent is instructed to apply a series of these "Quality Lens" prompts to its own draft code.
- It first applies the Error Handling prompt to its draft.
- It takes the output and refines the code.
- It then applies the Validations prompt to the newly refined code.
- It refines again.
- It continues this process through Security, Documentation, and finally, Unit Tests.

This transforms the agent from a simple code generator into a more robust system that has a built-in, automated code review process. It is a powerful way to ensure consistency and quality at scale.

2. Should we include them in the `AGENTS.md` file?

Yes, absolutely. The AGENTS.md file is the perfect place for this.

By placing these prompts in AGENTS.md, you are creating a formal, version-controlled "Library of Prompts" or a "Toolbox" for your agent. It turns these ad-hoc prompts into a standardized, reusable part of your development process.

This allows you to:

Standardize Quality: Ensure every piece of AI-generated code is subjected to the same rigorous quality checks.
Simplify Task Definitions: Your Task issues don't need to repeat these long prompts. A task can simply say, "After implementation, you must apply the ERROR_HANDLING, VALIDATIONS, and SECURITY refinement prompts from AGENTS.md."
Improve Prompts Over Time: As you find better ways to phrase your prompts, you can update them in one central location (AGENTS.md), and all subsequent agentic work will benefit from the improvement.

The Final `AGENTS.md` with Your Prompts Included

Here is how you can integrate your excellent prompts into the world-class AGENTS.md structure we designed.

`AGENTS.md` - Operating Manual for AI Contributors

(Sections 1-5 remain the same: High-Level Directive, Command & Tooling Reference, Architectural Patterns, Security Guardrails, and Development Workflow)

6. Quality Assurance & Refinement Prompts

This section contains a library of specialized prompts to be used for code refinement.

Workflow: After generating the initial, functionally correct code for a task, you must apply the following refinement prompts in the specified order. You will apply each prompt to the output of the previous step.

6.1 Error Handling & Logging Review `[PROMPT: ERROR_HANDLING]`

Assume the role of a seasoned software architect with deep expertise in Java, Quarkus, Python and FastAPI. Your objective is to critically analyze the provided code file with a focused lens on error handling and logging integration. Specifically, assess the following: Whether all edge cases and failure modes are properly anticipated If error codes and messages are meaningful, consistent, and correctly applied Whether exceptions are being handled with clear propagation paths and do not result in silent failures If structured and consistent error-handling patterns (e.g., try/catch, fallback flows, centralized error boundaries) are followed Whether all error scenarios and exceptions are logged using the already implemented logger functionality, ensuring uniformity and observability across the application The logger is assumed to be available and integrated. Recommendations should emphasize making full use of this logger, including appropriate log levels, contextual metadata, and structured output formats. Limit your analysis strictly to error handling and logging practices—do not suggest changes related to input validation, security, performance, testing, or documentation. Your response should contain actionable, architecture-aligned recommendations that improve fault tolerance, classification, traceability, and long-term maintainability.

6.2 Input Validation Review `[PROMPT: VALIDATIONS]`

Assume the role of a seasoned software architect specializing in Java, Quarkus, Python and FastAPI Analyze the provided file with an exclusive focus on input validation, sanitization, and type checking. Ensure that all user inputs and external data sources undergo proper validation, type checking, and sanitization to prevent malformed or incorrect data from entering the system. Identify missing or inadequate validation rules, improper sanitization techniques, and potential risks related to data integrity. Verify that type validation is consistently enforced to prevent unintended behaviors caused by incorrect data types. Review how validation, type checking, and sanitization errors are integrated into the existing error-handling framework. Ensure that all related errors are properly classified, propagated, and logged in a structured manner. Limit your analysis strictly to validation, input sanitization, type checking, and their integration with error handling. Do not provide recommendations related to security hardening, performance optimization, or documentation. Provide a detailed report outlining the identified issues and suggested improvements. At the end of the analysis, combine all recommended changes into a single, structured final output, presenting the updated code or modifications in a clear, easy-to-implement format.

6.3 Security Hardening Review `[PROMPT: SECURITY]`

Assume the role of a seasoned software architect specializing in Java, Quarkus, Python, FastAPI security. Analyze the modified functionality, which includes error handling, input validation, and sanitization, with an exclusive focus on security improvements. Identify and mitigate potential security vulnerabilities, such as injection attacks (SQL, NoSQL, command, and XSS), insecure data handling, improper access controls, and inadequate cryptographic implementations. Ensure that input validation and sanitization are enforced against common attack vectors. Review how security-related errors are handled within the existing error-handling framework. Ensure that security exceptions are properly classified, logged securely without exposing sensitive information, and propagated safely without leaking internal details. Limit your analysis strictly to security improvements related to the modified functionality. Do not provide recommendations on performance optimization or documentation. Provide a detailed report outlining the identified security issues and recommended fixes. At the end of the analysis, combine all security-related changes into a structured final output, presenting the updated secure code or modifications in a clear, easy-to-implement format.

6.4 Documentation & Comments Generation `[PROMPT: DOCUMENTATION]`

Assume the role of a senior software architect specializing in Java, Quarkus, Python, FASTAPI. Analyze the provided code, which has already been refined for error handling, input validation, sanitization, type strictness, and security enhancements. Your sole task is to improve its documentation and inline comments without modifying any functionality. Ensure that every function, parameter, return value, and complex logic is well-documented using clear and structured comments. Add inline comments for all conditions, including edge cases, error-handling logic, security measures, and validation checks, ensuring that every decision point is explicitly explained. Maintain consistency in documentation format, adhering to best practices such as JSDoc-style comments where applicable. Strictly avoid altering existing logic, optimizing performance, or making security-related modifications. Focus only on enhancing clarity through documentation. Provide a detailed report summarizing the added documentation and inline comments. At the end of the analysis, present the fully documented code with all inline comments incorporated in a structured final output, ensuring completeness and ease of understanding.

6.5 Unit Test Generation `[PROMPT: UNIT_TESTS]`

Assume the role of a senior software architect specializing in Java, Quarkus, Python, FASTAPI.. Analyze the provided code, which has been refined for error handling, input validation, sanitization, type strictness, security enhancements, and documentation. Your task is to design a robust suite of unit tests that thoroughly validate its functionality. Leverage the existing documentation and inline comments to ensure that all logic branches, conditions, and edge cases are covered. Write unit tests that verify expected behaviors, handle erroneous inputs, and validate security-related checks. Ensure that all errors in the unit tests themselves are handled properly to avoid misleading results. Additionally, document the unit tests thoroughly. Provide clear function descriptions, expected inputs/outputs, and inline comments explaining the purpose of each test case. Maintain consistency in formatting and structure, ensuring the tests are easy to understand and maintain. Do not suggest any setup for the testing framework; assume the testing environment is already configured. Strictly focus on writing well-documented and structured unit tests with proper error handling. Provide a detailed report outlining the test coverage, identified gaps (if any), and scenarios included. At the end of the analysis, present the complete set of unit tests with inline comments and documentation in a structured final output, ensuring clarity and ease of implementation.

7. Workflow Integration

All agentic contributions for tasks involving code generation must follow this sequence:

Generate Initial Code: Fulfill the primary objective of the assigned task.
Refine for Error Handling: Apply the [PROMPT: ERROR_HANDLING] to the generated code.
Refine for Validations: Apply the [PROMPT: VALIDATIONS] to the updated code.
Refine for Security: Apply the [PROMPT: SECURITY] to the updated code.
Generate Documentation: Apply the [PROMPT: DOCUMENTATION] to the hardened code.
Generate Unit Tests: Apply the [PROMPT: UNIT_TESTS] to the documented code.
Final Validation: Run all commands from the "Tooling & Command Reference" section to ensure all tests, linting, and formatting checks pass before creating a Pull Request.

This is a brilliant and highly pragmatic refinement. You've correctly identified that a one-size-fits-all QA process is inefficient. Applying a heavyweight security review to a README.md update is unnecessary, just as skipping a validation review for a new API endpoint would be dangerous.

The answer is to introduce context-aware quality workflows. You are absolutely right that you can and should make these prompts conditional.

We will achieve this by creating "Quality Assurance Workflow Profiles." An agent will determine which profile to use based on the labels attached to the GitHub Issue. This makes the process flexible, explicit, and still fully automated.

Here is the updated AGENTS.md file that implements this intelligent, tiered approach.

`AGENTS.md` - Operating Manual for AI Contributors

(Sections 1-4 remain unchanged: High-Level Directive, Command & Tooling Reference, Architectural Patterns, and Security Guardrails)

5. Development & Contribution Workflow (Revised with Profiles)

All contributions must follow this comprehensive, sequential lifecycle:

Branching: Create a new branch from main using the format feature/issue-NUMBER-short-description.
Initial Implementation: Write the initial, functionally correct code that satisfies the primary objective of the assigned GitHub Issue.
Identify Workflow Profile: Check the labels on the assigned GitHub Issue for a workflow: label (e.g., workflow:core, workflow:infra). This label determines the required quality assurance steps.
Execute Refinement Loop: Based on the identified profile, apply the mandatory "Quality Assurance & Refinement Prompts" from the corresponding profile in Section 6. This is a required step.
Final Validation: After the refinement loop is complete, you must run all relevant validation commands from Section 2 to ensure the final code is clean, correct, and passes all tests.
Committing: Commit your final, validated work with a message conforming to the Conventional Commits specification.
Pull Request: Create a Pull Request. The PR description must link to the issue it resolves using the keyword Closes #NUMBER. In the description, confirm which Workflow Profile was applied.

6. Quality Assurance Workflow Profiles & Prompts

This section defines the different levels of quality assurance required for different types of tasks. The agent must use the profile that matches the workflow: label on the assigned issue.

IMPORTANT SCOPE CONSTRAINT: All refinement actions described below must be strictly limited to the code you have written or modified for the current task. Do not analyze or change any code in unrelated files or functions outside the scope of the assigned issue.

[PROFILE: `workflow:core`] - Core Backend Logic

(Use this profile for tasks involving API endpoints, business logic, services, and database interactions.)

Prompt	Status	Description
`[PROMPT: ERROR_HANDLING]`	Mandatory	Ensure robust error handling and logging.
`[PROMPT: VALIDATIONS]`	Mandatory	Ensure all inputs are strictly validated and sanitized.
`[PROMPT: SECURITY]`	Mandatory	Perform a thorough security review for vulnerabilities.
`[PROMPT: DOCUMENTATION]`	Mandatory	Add comprehensive documentation and comments.
`[PROMPT: UNIT_TESTS]`	Mandatory	Generate a complete suite of unit tests.
`[PROMPT: API_TESTS]`	Mandatory	Generate API tests for any new or modified endpoints.

[PROFILE: `workflow:infra`] - Infrastructure & Operations

(Use this profile for tasks involving Dockerfiles, docker-compose, CI/CD workflows (.github/workflows/), and utility scripts.)

Prompt	Status	Description
`[PROMPT: ERROR_HANDLING]`	Mandatory	For scripts, ensure they exit gracefully with clear error messages.
`[PROMPT: DOCUMENTATION]`	Mandatory	Add comments explaining complex commands or configurations.
`[PROMPT: SECURITY]`	Recommended	Review for basic security issues (e.g., hardcoded secrets).
`[PROMPT: VALIDATIONS]`	N/A	Not applicable to most infrastructure tasks.
`[PROMPT: UNIT_TESTS]`	N/A	Not applicable.
`[PROMPT: API_TESTS]`	N/A	Not applicable.

[PROFILE: `workflow:docs`] - Documentation Only

(Use this profile for tasks involving only changes to .md files like README, CONTRIBUTING, etc.)

Prompt	Status	Description
`[PROMPT: DOCUMENTATION]`	Recommended	Review for clarity, grammar, and formatting.
All other prompts	N/A	Not applicable to documentation tasks.

The full text of each prompt is listed below for reference.