Skip to content

Add AGENT.md rules#11397

Merged
DzikuVx merged 1 commit intomasterfrom
dzikuvx-help-ai-agents
Mar 5, 2026
Merged

Add AGENT.md rules#11397
DzikuVx merged 1 commit intomasterfrom
dzikuvx-help-ai-agents

Conversation

@DzikuVx
Copy link
Member

@DzikuVx DzikuVx commented Mar 4, 2026

Let's help agents a little

@DzikuVx DzikuVx added this to the 9.1 milestone Mar 4, 2026
@github-actions
Copy link

github-actions bot commented Mar 4, 2026

Branch Targeting Suggestion

You've targeted the master branch with this PR. Please consider if a version branch might be more appropriate:

  • maintenance-9.x - If your change is backward-compatible and won't create compatibility issues between INAV firmware and Configurator 9.x versions. This will allow your PR to be included in the next 9.x release.

  • maintenance-10.x - If your change introduces compatibility requirements between firmware and configurator that would break 9.x compatibility. This is for PRs which will be included in INAV 10.x

If master is the correct target for this change, no action is needed.


This is an automated suggestion to help route contributions to the appropriate branch.

@qodo-code-review
Copy link
Contributor

Review Summary by Qodo

Add comprehensive AGENT.md guide for AI developers

📝 Documentation

Grey Divider

Walkthroughs

Description
• Comprehensive AI agent guide for INAV flight controller firmware
• Covers architecture, coding conventions, build system, and key concepts
• Includes development workflow, common patterns, and important guidelines
• Provides quick reference and resources for contributors
Diagram
flowchart LR
  A["INAV Project Overview"] --> B["Architecture & Structure"]
  B --> C["Coding Conventions"]
  C --> D["Build System"]
  D --> E["Key Concepts"]
  E --> F["Development Workflow"]
  F --> G["AI Agent Guidelines"]
  G --> H["Quick Reference"]
Loading

Grey Divider

File Changes

1. AGENT.md 📝 Documentation +461/-0

Complete developer guide for INAV firmware

• New comprehensive guide document for AI agents working with INAV codebase
• Covers project overview, architecture, directory structure, and core components
• Documents coding conventions including naming, style, and memory attributes
• Explains build system, CMake process, and target configuration
• Details key concepts like Parameter Groups, Scheduler, sensors, and MSP protocol
• Provides common patterns for hardware abstraction, error handling, and filtering
• Includes development workflow, branching strategy, and PR guidelines
• Lists AI agent guidelines for features, bug fixes, refactoring, and common pitfalls
• Contains quick reference with file patterns, abbreviations, and resources

AGENT.md


Grey Divider

Qodo Logo

@qodo-code-review
Copy link
Contributor

qodo-code-review bot commented Mar 4, 2026

Code Review by Qodo

🐞 Bugs (3) 📘 Rule violations (0) 📎 Requirement gaps (0)

Grey Divider


Action required

1. SLOW_RAM mislabeled deprecated 🐞 Bug ✓ Correctness
Description
AGENT.md states SLOW_RAM is deprecated (“do not use”), but the codebase still defines and uses it,
which may prompt agents to remove/avoid it and break memory placement on affected MCUs.
Code

AGENT.md[R86-92]

+```c
+FASTRAM                     // Fast RAM section (aligned)
+EXTENDED_FASTRAM            // Extended fast RAM (STM32F4/F7 only)
+DMA_RAM                     // DMA-accessible RAM (STM32H7, AT32F43x)
+SLOW_RAM                    // Slower external RAM - deprecated, o not use
+STATIC_FASTRAM              // Static variable in fast RAM
+STATIC_FASTRAM_UNIT_TESTED  // Static fast RAM variable visible in unit tests
Evidence
The build config defines SLOW_RAM for STM32H7/AT32F43x, and production code still uses it for EEPROM
buffering; therefore calling it deprecated is incorrect and risky guidance.

AGENT.md[86-93]
src/main/build/build_config.h[54-63]
src/main/config/config_streamer.c[24-26]

Agent prompt
The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
AGENT.md incorrectly marks `SLOW_RAM` as deprecated even though it is still defined and used in production code. This can mislead agents into removing or avoiding `SLOW_RAM` usage, potentially breaking memory placement.

## Issue Context
`SLOW_RAM` is defined in `src/main/build/build_config.h` and is used (e.g., for EEPROM buffering) in `src/main/config/config_streamer.c`.

## Fix Focus Areas
- AGENT.md[86-92]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools



Remediation recommended

2. Misleading build dir path 🐞 Bug ✓ Correctness
Description
AGENT.md refers to the build directory as /build and the build example starts with cd build
without creating it, which can lead agents to try an absolute path or hit a missing-directory build
failure.
Code

AGENT.md[R112-121]

+3. **Build Directory**: Always use out-of-source builds in `/build` directory
+
+### Building a Target
+
+```bash
+# From workspace root
+cd build
+cmake ..
+make MATEKF722SE     # Build specific target
+make                 # Build all targets
Evidence
AGENT.md uses an absolute-looking /build and omits the documented first-time mkdir build step.
The existing Linux build doc explicitly describes creating a *relative* build directory inside the
repo before entering it.

AGENT.md[110-122]
[docs/development/Building in Linux.md[74-83]](https://github.com/iNavFlight/inav/blob/873e9d6480e054cb754ed24f290343c26f37058b/docs/development/Building in Linux.md/#L74-L83)

Agent prompt
The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
AGENT.md’s build instructions can mislead users into treating `build` as an absolute path (`/build`) and/or failing because the example omits creating the directory.

## Issue Context
The repo’s existing build documentation uses a relative `build` directory created within the repo and explicitly includes `mkdir build` before `cd build`.

## Fix Focus Areas
- AGENT.md[112-121]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools


3. Unaligned coding standard 🐞 Bug ✓ Correctness
Description
AGENT.md instructs agents to follow MISRA C rules, but the project’s own developer guidance points
to the Baseflight coding style/clean-code principles; this can create conflicting expectations for
contributions.
Code

AGENT.md[R353-357]

+5. **Update Documentation**: Add/update files in `/docs` 
+6. **Consider Target Support**: Use `#ifdef USE_FEATURE` for optional features
+7. **Generate CLI setting docs**: Remember to inform user to run `python src/utils/update_cli_docs.py`
+8. **Follow conding standard**: Follow MISRA C rules
+9. **Increase Paremeterer Group Version**: When changing PG structure, increase version corresponding in `PG_REGISTER`, `PG_REGISTER_WITH_RESET_FN`, `PG_REGISTER_WITH_RESET_TEMPLATE`, `PG_REGISTER_ARRAY` or `PG_REGISTER_ARRAY_WITH_RESET_FN`
Evidence
The existing developer documentation explicitly points contributors at Baseflight’s coding style and
general clean-code guidance; AGENT.md should align to that (or clearly justify MISRA and link to
repo tooling/policy if intended).

AGENT.md[353-357]
docs/development/Development.md[21-23]

Agent prompt
The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
AGENT.md introduces a MISRA C requirement that is not aligned with the repo’s documented coding-style guidance, which can confuse contributors/agents.

## Issue Context
`docs/development/Development.md` points to Baseflight’s coding style and clean-code principles. AGENT.md should align to that, or clearly document MISRA enforcement and where it is defined.

## Fix Focus Areas
- AGENT.md[353-357]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools


Grey Divider

ⓘ The new review experience is currently in Beta. Learn more

Grey Divider

Qodo Logo

Comment on lines +86 to +92
```c
FASTRAM // Fast RAM section (aligned)
EXTENDED_FASTRAM // Extended fast RAM (STM32F4/F7 only)
DMA_RAM // DMA-accessible RAM (STM32H7, AT32F43x)
SLOW_RAM // Slower external RAM - deprecated, o not use
STATIC_FASTRAM // Static variable in fast RAM
STATIC_FASTRAM_UNIT_TESTED // Static fast RAM variable visible in unit tests
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Action required

1. Slow_ram mislabeled deprecated 🐞 Bug ✓ Correctness

AGENT.md states SLOW_RAM is deprecated (“do not use”), but the codebase still defines and uses it,
which may prompt agents to remove/avoid it and break memory placement on affected MCUs.
Agent Prompt
## Issue description
AGENT.md incorrectly marks `SLOW_RAM` as deprecated even though it is still defined and used in production code. This can mislead agents into removing or avoiding `SLOW_RAM` usage, potentially breaking memory placement.

## Issue Context
`SLOW_RAM` is defined in `src/main/build/build_config.h` and is used (e.g., for EEPROM buffering) in `src/main/config/config_streamer.c`.

## Fix Focus Areas
- AGENT.md[86-92]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

@DzikuVx DzikuVx merged commit 78a96e3 into master Mar 5, 2026
2 checks passed
@DzikuVx DzikuVx deleted the dzikuvx-help-ai-agents branch March 5, 2026 08:22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant