Proposal: add an AGENTS.md for AI coding agents

[zhubonan]

Many AI coding tools (Claude Code, Cursor, Copilot, etc.) read a repo-level instructions file to understand conventions, build setup, and coding style. ABACUS is a large C++ codebase with a complex CMake build and specific conventions — an AGENTS.md would help AI agents (and human contributors) get up to speed faster.

A minimal one could cover:

• Build commands (cmake options commonly used)
• Coding style (follow clang-format/clang-tidy)
• How to run tests
• Directory layout overview

Open to feedback — I can draft the content if this sounds good.

[endgegnerbert-tech]

For an ABACUS-sized C++ codebase, the most useful AGENTS.md sections would be: (1) which build system commands map to debug/release/test, (2) where the hot loops live (probably in src/), and (3) a minimal "don't touch these files without asking" list. The DFT/MD code paths have very different performance profiles — an agent needs to know which one it's modifying before it can reason about correctness.

[mohanchen]

That's a great idea!

[mohanchen]

I will propose some rules: Project Coding Specification

1. Global Variable Usage Convention
   The project provides three global accessible types: GlobalV, GlobalC, and PARAM. These exist only as temporary compatibility solutions for legacy code. For all new code development, do not use these global variables. Instead, pass variables explicitly through function parameters to achieve better code decoupling and maintainability.
2. Restriction on Member Variables for Logical Judgment
   Avoid using member variables to store logical judgment states that are shared and switched between multiple functions and classes. Member variables act as module-scoped global states. They can be modified implicitly by different functions without explicit parameter passing, which may accidentally override the original design logic and cause unpredictable functional errors.
3. Strict Header File Dependency Control
   Avoid including unnecessary .h header files inside other header files. Uncontrolled header inclusion will create extremely long and fragile dependency chains. Any modification or error in the depended header files may indirectly affect the correctness of the current project code.
4. HPP File Usage Specification
   Files with .hpp suffix usually contain complete implementation details. Including such files in multiple places will bring heavy compilation and dependency burdens. It is recommended to avoid using .hpp files. Split the code into separate .h declaration files and .cpp implementation files. If .hpp files are necessary, do not reference them in any other public header files.
5. EXX Module Dependency Optimization Plan
   The current project has a complicated and deep dependency chain associated with EXX-related code. This part of the code will be reconstructed in subsequent versions to reduce overall project coupling.
6. Prohibition of New Default Parameters for Existing Functions
   Do not add new parameters with default values to existing functions. Although this approach seems compatible with legacy code, it will implicitly inject new logic into all legacy call sites during compilation. Most developers are unaware of such hidden dependencies, which will introduce potential logic bugs during subsequent code iteration and feature development. The mandatory rule is to remove all default parameter values. All parameters must be explicitly passed, so that every developer can clearly recognize and consider all function input options.
7. Unit Test Specification for Core Functions
   All critical and core business functions must be covered by corresponding unit tests to ensure functional correctness. AI tools can be used to assist unit test writing, but the test cases must be concise and effective. Avoid overly lengthy and redundant unit test code that increases project maintenance costs.

[Growl1234]

I think, beyond AI coding agents, new contributors would also benefit from a concise, repository-specific guide explaining how to navigate the codebase, build and test changes locally, and follow the project’s development conventions. As long as it remains focused on such practical guidance rather than duplicating the full documentation or CI configuration, AGENTS.md could serve this purpose well.

[QuantumMisaka]

@zhubonan @endgegnerbert-tech You may like to have a view in #7505, thanks!