rt-thread/AGENTS.md

RT-Thread AI Agent Rules

本文件用于约束在本仓库内工作的 AI Agent（如 Codex）。如无明确说明，所有修改都应遵循“最小改动、问题导向、可验证”原则。

1. 可以做什么

• 阅读仓库内与任务直接相关的代码、文档、配置和测试文件。
• 仅针对当前任务做最小必要修改，并同步更新直接相关的文档或测试。
• 优先复用现有目录结构、脚本、构建流程与测试流程。
• 在提交前运行与改动直接相关的现有检查、构建或测试，并确认结果。
• 在不改变原有行为的前提下，修复改动直接引入的问题。

2. 明令禁止

• 禁止修改与当前任务无关的代码、文档、格式或测试。
• 禁止大规模重构、批量重命名、全仓格式化，除非任务明确要求。
• 禁止提交生成物、临时文件、日志、二进制文件或本地环境文件。
• 禁止引入密钥、口令、令牌、证书或其他敏感信息。
• 禁止随意升级依赖、替换第三方代码或改动外部导入代码，除非任务明确要求且已验证影响。
• 禁止删除或弱化已有测试来规避失败。
• 禁止改写历史（rebase、squash、force push 等）或覆盖他人工作成果。

3. 目录规则

请按照仓库既有职责放置文件，禁止随意新增同类平行目录：

• bsp/：开发板、芯片、板级支持包相关代码。
• components/：内核外围组件、中间件、软件包适配代码。
• documentation/：通用文档、开发规范、使用说明。
• examples/：示例、演示代码、utest 配置与样例。
• include/：对外公开的头文件。
• libcpu/：架构、CPU 相关移植代码。
• src/：RT-Thread 内核核心源码。
• tools/：构建、CI、辅助脚本。

新增文件时请遵循以下要求：

• 文档优先放在 documentation/；仅仓库级规则文档放在根目录。
• 公共接口声明放在 include/ 或对应模块公开头文件中，不要散落在无关目录。
• 板级、芯片级改动应限制在对应 bsp/、libcpu/ 或驱动目录内。
• 示例和测试代码不要放入内核核心目录。

4. 文件规则

• 目录名、文件名如无特殊原因，使用小写；引用的第三方或上游文件可保留原名。
• 新增驱动源码文件命名遵循 drv_class.c 风格，例如 drv_spi.c。
• 新增 C 头文件应使用统一的 include guard 风格，例如 __FILE_H__。
• 新增源码文件应补齐版权、SPDX-License-Identifier 与必要的 Change Log，风格与现有代码保持一致。
• 代码注释使用英文；文档可按所在文档语言编写。
• 修改 README 或说明文档时，优先更新与改动内容直接对应的语言版本，避免制造互相矛盾的描述。
• 非任务必须，不要修改第三方库、自动生成文件和体量巨大的导入文件。

5. 提交流程要求

• 修改前先确认影响范围，只处理当前 issue 或 review feedback。
• 修改后至少执行与改动直接相关的现有校验；无法执行时需在说明中明确原因。
• 提交内容应保持干净、聚焦，避免混入无关改动。
• 若发现仓库现有规则与本文件冲突，以更具体的目录文档、贡献指南和编码规范为准：
  • .github/CONTRIBUTING.md
  • documentation/7.contribution/coding_style_cn.md