Ada AGENT.md files

General
1

I just began to use cli IA help in coding (here Mistral vibe).
It kind of works, but is sometimes akward because of ignorance of the Ada dev environment.
For example, it try to ensure that the modified source is well compiled by greping one of the created identifier in the executable file!

The LLM needs more information. Some are depedant on individual choices, for example your version numbering and publishing process, but some are more generic, for example using Alire to update dependencies or identify imported lib, etc.

I found an initiative called AGENTS.md :

README.md files are for humans: quick starts, project descriptions, and contribution guidelines.

AGENTS.md complements this by containing the extra, sometimes detailed context coding agents need: build steps, tests, and conventions that might clutter a README or aren’t relevant to human contributors.

It provides simple guidelines to create agent files, and references to thousands of existing AGENT.md files of all kinds, that give the AI guidelines on “howto” use dev tools, or on coding guidelines, testing policies, etc.
However, I don’t recall seeing any for Ada.

Are you aware of any such files for Ada, either generic or specialized (Alire, SPARK, AUnit, GNAT tooling, etc.)?

To avoid everyone reinventing the wheel, my idea could be to have a “master” AGENT.md that is specific to my project, but that references other files made available by the community. My ownAGENT.md could reference aunit.md or ahven.md depending on my preferences for unit testing.

1 Like
2

I’m not really knowledgeable about Ai assistance but I have seen some github projects use .github/copilot-constructions.md for copilot. Maybe this might be something for you?

Alire has one but I have never used or tested it.

As how to setup other Ai tools, I have no idea.

1 Like
3

I have such files, but mainly to enforce a naming convetion.
I will share that later (I am aware from computer).

To my knowledge, I have not seen that for Ada, but it could be helpful.

On my side I have tried “AI” IDE (Windsurf, Cursor, Kilo), and terminal, Claude Code and OpenCode. I currently use Claude Code and OpenCode (I don’t know which one is better., but probably OpenCode ‘cause you can use the LLM you want).
But, TLDR: It does not replace humain, you still needs a human that really understand the language and so, what the LLM produce, even with the strictness of Ada/SPARK.

1 Like
4

Thanks, this is a good example AGENT.md.

It target Github Copilot, but is usable as is with Codex / Codestral / Claude, etc. (this is the beauty of LLM, they understand natural language, there is no precise format required to be useful). You just need to tell your code assistant where to find it, unless it uses the default dir/name.

But this one is for Alire developers/contributors (it expose for example some coding convention for Alire code).
The idea of AGENTS.md is to expose the user side view of Alire. It would for example explain howto run the test suite (`alr test`) or how to build your software (`alr build`), so that the code assistant of all projects using Alire could easily integrate it.

(Another md file could target Alire package authors, explaining how to to manage your package version number according to Alire convention and how to to publish your package.)

This is like a README for LLM, and as such it should be exposed in the root directory, or maybe in the doc dir, not in the hidden github directory.
(And I am convinced that this is now to be considered almost as important as the README file if you want your tool/component to be easy to adopt).

5

On my side I only have a ada-style-guide.md:

---
trigger: glob
globs: *.ads,*.adb
---

# Ada Code Conformance Review and Refactoring Assistant

This short document defines coding conventions for Ada developers.

## Naming Conventions to Enforce

### Mandatory Naming Rules

| Element | Convention | Pattern/Rule | Example |
|---------|------------|--------------|---------|
| **Packages** | Pascal_Case with underscore | Noun phrases describing abstraction | `Command_Line_Parser` |
| **Types** | Pascal_Case with underscore | Descriptive nouns | `User_Account_Type` |
| **Subtypes** | Pascal_Case with underscore | Descriptive with constraints | `Valid_Port_Range` |
| **Constants** | ALL_CAPS with underscore | Descriptive, avoid magic numbers | `MAX_RETRY_ATTEMPTS` |
| **Variables** | Pascal_Case with underscore | Intention-revealing nouns | `Current_User_Session` |
| **Procedures** | Pascal_Case | `<Verb><Object><State>` pattern | `Initialize_Database_Connection` |
| **Functions (Boolean)** | Pascal_Case | Predicate clauses (Is_/Has_/Can_/Was_) | `Is_Valid_Email_Address` |
| **Functions (Non-Bool)** | Pascal_Case | Descriptive nouns | `Calculate_Tax_Amount` |
| **Parameters** | Pascal_Case with underscore | Context-specific, descriptive | `Source_File_Path` |
| **Exceptions** | E_Pascal_Case | Error condition description | `E_Invalid_Configuration` |
| **Access Types** | Pascal_Case_Ptr | Clear pointer indication | `User_Account_Ptr` |

### Special Prefixes/Suffixes

- **Interfaces**: `I_` prefix (e.g., `I_Payment_Processor`)
- **Abstract types**: `Abstract_` prefix (e.g., `Abstract_Database_Driver`)
- **Private types**: `_Type` suffix (e.g., `Internal_State_Type`)
- **Arrays**: `_Array` suffix (e.g., `User_Accounts_Array`)
- **Protected Types**: `Protected_` prefix (e.g., `Protected_Message_Queue`)
- **Task Types**: `Task_` prefix (e.g., `Task_Background_Processor`)

## Documentation Requirements

### Package Headers (Mandatory)
Every package must have a comprehensive header:

```ada
--------------------------------------------------------------------------------
--  <project_name> - <project_description>
--  Copyright (c) <year>
--  SPDX-License-Identifier: <license>
--------------------------------------------------------------------------------

--  Package: <Package_Name>
--  
--  Purpose: <Clear description of package responsibility>
--
--  Responsibilities:
--    * <Specific responsibility 1>
--    * <Specific responsibility 2>
--    * <Specific responsibility 3>
--
--  Design Notes (optional):
--    <Description of the package, its intent, etc.>
--
--  External Effects: <Describe side effects or "None" for pure packages>
--  Thread Safety: <Describe thread safety guarantees>
--  SPARK Status: <Compatible/Verified/Not Applicable>
```

### Subprogram Documentation (Required for Public Interface)
All public subprograms need documentation:

```ada
--  <Brief description of what the subprogram does>
--
--  <Detailed description including algorithm, business rules, formula, etc.>
--
--  Time Complexity: <If relevant>
--  Side Effects: <List any side effects>
--
--  **Preconditions:** <If relevant>
--    - <condition 1>
--    - <condition 2>
--
--  **Postconditions:** <If relevant>
--    - <guarantee>
--
--  **SPARK Verification:** <If relevant>
--    - <notes>
--
--  **Usage Example:**
--
--     <code>
--
--  @param <Parameter_Name> <Description of parameter>
--  @return <Description of return value>
--  @exception <Exception_Name> <When this exception is raised>
```

### Type Documentation (When Not Self-Evident)
Document complex types, especially records and enumerations:

```ada
-- <Brief description of the type>
-- <Usage context and constraints>
type <Type_Name> is record
   <Field_Name> : <Type>;  -- <Field description if not obvious>
   <Field_Name> : <Type>;  -- <Field description if not obvious>
end record;
```

### Function Naming

- **Boolean functions**: Must use predicate patterns
  - `Is_Valid` → `Is_Valid_[Context]`
  - `Check_Status` → `Has_Valid_Status` or `Is_Status_Valid`
  - `Validate` → `Is_Valid_[What]`

- **Non-boolean functions**: Should be descriptive nouns
  - `Get_Data` → `Current_[Specific_Data]` or `Calculate_[Result]`
  - `Process` → `Process_[What]_[How]`

### Procedure Naming

- Must follow `<Verb><Object><Context>` pattern:
  - `Setup` → `Initialize_[System/Component]`
  - `Handle_Request` → `Process_[Type]_Request`
  - `Update` → `Update_[What]_[Attribute]`

### Variable and Parameter Naming

- Avoid abbreviations and single letters (except standard loop counters)
- Use intention-revealing names:
  - `Data` → `[Specific_Data_Type]`
  - `Info` → `[Specific_Information]`
  - `Temp` → `Temporary_[Purpose]`

It is used by AI client (here Windsurf) to know my coding standard guide line for a project.
I have no global AGENT.md, I found that is mosly project specific. But we can see to create one with projet aware things, like if a project use alire, then use alr build to build otherwise gprbuild -P project.gpr -j0, etc.

On the subject of writing such files, I found:

1 Like
6

Thanks a lot, very interresting, and so are the two links.

7

I have Ada-specific agent instructions file in my TinYAML repo.

1 Like