Xyea的知识库

切换主题

Best Practices for Writing AGENT.md for OpenAI Codex and Google Gemini CLI ​

字数
1662 字
阅读时间
8 分钟

为 OpenAI Codex 和 Google Gemini CLI 撰写 AGENT.md 的最佳实践

Key Recommendation:  关键建议：
Place a well-structured AGENT.md (or GEMINI.md) file at the root of your repository to serve as the canonical “project memory” for AI coding agents. This file should include project architecture, coding standards, testing conventions, and non-negotiable rules to ensure consistency, quality, and security when using OpenAI Codex or Google Gemini CLI.
在你的存储库根目录下放置一个结构良好的 AGENT.md （或 GEMINI.md ）文件，作为 AI 编码代理的规范“项目记忆”。该文件应包括项目架构、编码标准、测试约定以及不可协商的规则，以确保在使用 OpenAI Codex 或 Google Gemini CLI 时的一致性、质量和安全性。

1. File Placement and Naming ​

  1. 文件放置与命名

  • Name the file AGENT.md for OpenAI Codex and GEMINI.md for Google Gemini CLI (both tools support either name if configured).
    将 OpenAI Codex 的文件命名为 AGENT.md，将 Google Gemini CLI 的文件命名为 GEMINI.md（如果配置正确，两个工具都支持这两个名称）。

  • Place it in the repository root (or in .gemini/ for global defaults) so the agent auto-loads context on each session.agentsmd+1
    将其放置在存储库根目录中（或在 .gemini/ 中设置全局默认值），以便代理在每个会话中自动加载上下文。agentsmd +1

2. Project Structure Overview ​

  1. 项目结构概述

Describe your codebase layout to guide context navigation:
描述你的代码库布局，以指导上下文导航：

  • List directories with roles (e.g., /src, /components, /utils, /tests).
    列出具有不同角色的目录（例如， /src 、 /components 、 /utils 、 /tests ）。

  • Highlight modules requiring special handling (e.g., “do not modify /public assets directly”).saif71+1
    突出显示需要特殊处理的模块（例如，“请勿直接修改 /public 资产”）。saif71 +1

3. Coding Conventions  3. 编码规范 ​

Document style and language rules to enforce uniform output:
记录样式和语言规则以确保输出一致：

  • Language-specific standards (TypeScript vs. Python): naming conventions, preferred libraries, file-naming (e.g., PascalCase for React components).wandb+1
    特定语言标准（TypeScript 与 Python）：命名规范、首选库、文件命名（例如，React 组件使用帕斯卡命名法）。wandb +1

  • Linting/formatting: reference root ESLint/Prettier configs to avoid hidden divergences.saif71
    代码检查/格式化：参考根目录下的 ESLint/Prettier 配置，以避免潜在的差异。saif71

  • Comments and documentation: require meaningful comments for complex logic and link to contributing guides or README conventions.agentsmd+1
    注释和文档：对于复杂逻辑需要有意义的注释，并链接到贡献指南或 README 约定。agentsmd + 1

4. Testing Guidelines  4. 测试指南 ​

Ensure AI-generated code includes adequate tests:
确保由人工智能生成的代码包含足够的测试：

  • Commands to run tests (e.g., npm test, pytest) and coverage thresholds.wandb+1
    运行测试的命令（例如， npm test ， pytest ）以及覆盖阈值。wandb+1

  • Specify frameworks (e.g., JUnit, PyTest) and organizational patterns (e.g., one test file per module).wandb
    指定框架（例如，JUnit、PyTest）和组织模式（例如，每个模块一个测试文件）。wandb

  • Encourage test-driven approach by stating “all new features require accompanying unit tests”.wandb
    通过声明“所有新功能都需要附带单元测试”来鼓励测试驱动的方法。wandb

5. Task Decomposition and Prompts ​

  1. 任务分解与提示

Help the agent break down large tasks:
帮助智能体分解大型任务：

  • Provide examples of high-level goals decomposed into stepwise prompts.
    提供分解为逐步提示的高层次目标示例。

  • Include preferred prompt templates or examples for code generation, refactoring, and documentation tasks.softwareplanetgroup
    包括代码生成、重构和文档任务的首选提示模板或示例。softwareplanetgroup

6. Self-Correction and Review Workflow ​

  1. 自我修正与审查工作流程

Integrate quality checks into AI flow:
将质量检查集成到人工智能流程中：

  • Instruct use of CLI commands to preview changes (e.g., gemini edit shows diffs).softwareplanetgroup
    指示使用 CLI 命令预览更改（例如， gemini edit 显示差异）。softwareplanetgroup

  • Encourage manual diff review or CI-driven “read-only” analysis mode before auto-applying edits.softwareplanetgroup
    在自动应用编辑之前，鼓励进行手动差异审查或由持续集成（CI）驱动的“只读”分析模式。softwareplanetgroup

7. Security and Compliance ​

  1. 安全与合规

Protect secrets and enforce safe practices:
保护机密信息并执行安全实践：

  • Mandate use of environment variables for secrets; prohibit hard-coding API keys in code.wandb
    强制使用环境变量来存储机密信息；禁止在代码中硬编码 API 密钥。wandb

  • List any regulatory or security requirements (e.g., input sanitization, parameterized SQL statements for injection prevention).wandb
    列出任何监管或安全要求（例如，输入清理、用于防止注入的参数化 SQL 语句）。wandb

8. Non-Negotiable Rules  8. 不可协商的规则 ​

State forbidden actions explicitly:
明确说明禁止的操作：

  • E.g., “DO NOT modify .env or Terraform state files” or “never change code outside /src”.saif71
    例如，“请勿修改 .env 或 Terraform 状态文件”或“切勿在 /src 之外更改代码”。saif71

  • These hard constraints help the agent avoid destructive edits and respect workspace safety.saif71
    这些严格的约束有助于智能体避免进行破坏性编辑并尊重工作区安全。saif71

9. Context Modularity and Updates ​

  1. 上下文模块化与更新

Manage complexity and evolution of AGENT.md:
管理 AGENT.md 的复杂性与演进：

  • For large projects, break context into multiple Markdown files and import via @file.md syntax.saif71
    对于大型项目，将上下文拆分为多个 Markdown 文件，并通过 @file.md 语法进行导入。saif71

  • Regularly update the file to reflect architecture changes, new standards, or tooling updates.saif71
    定期更新文件，以反映架构变更、新标准或工具更新。saif71

10. Cross-Tool Compatibility ​

  1. 跨工具兼容性

Adopt a tool-agnostic AGENT.md format:
采用与工具无关的 AGENT.md 格式：

  • Both OpenAI Codex and Google Gemini CLI (and other AI agents like Sourcegraph Amp) can consume the same file, ensuring unified guidance across platforms.wandb
    OpenAI Codex 和 Google Gemini CLI（以及其他类似 Sourcegraph Amp 的人工智能代理）都可以使用相同的文件，确保跨平台的统一指导。wandb

  • Use consistent section headers so each tool’s parser can locate relevant instructions reliably.
    使用一致的章节标题，以便每个工具的解析器都能可靠地定位相关说明。

By adhering to these best practices, your AGENT.md (or GEMINI.md) will empower AI coding agents to generate high-quality, consistent, and secure code that integrates seamlessly into your workflow—minimizing rework and accelerating development.
通过遵循这些最佳实践，你的 AGENT.md （或 GEMINI.md ）将使人工智能编码代理能够生成高质量、一致且安全的代码，无缝集成到你的工作流程中，从而最大限度地减少返工并加速开发。

  1. https://agentsmd.net
  2. https://softwareplanetgroup.co.uk/best-practices-for-using-gemini-cli/
  3. https://blog.saif71.com/gemini-cli-and-gemini/
  4. https://wandb.ai/wandb_fc/genai-research/reports/Introduction-to-Agents-md--VmlldzoxNDEwNDI2Ng
  5. https://openai.com/index/introducing-codex/
  6. https://developers.google.com/gemini-code-assist/docs/use-agentic-chat-pair-programmer
  7. https://www.linkedin.com/pulse/best-practices-coding-openai-codex-ronny-roeller-hnjee
  8. https://codelabs.developers.google.com/gemini-cli-hands-on
  9. https://help.openai.com/en/articles/6654000-best-practices-for-prompt-engineering-with-the-openai-api
  10. https://github.com/google-gemini/gemini-cli/discussions/1471
  11. https://www.linkedin.com/posts/robennals_using-codex-well-experiences-so-far-activity-7338041426204602371-Ej08
  12. https://blog.google/technology/developers/introducing-gemini-cli-open-source-ai-agent/
  13. https://sgryphon.gamertheory.net/2025/07/agents-md-standardisation-for-agentic-coding-systems/
  14. https://ikala.ai/blog/ai-trends/google-gemini-cli-in-depth-analysis-the-ai-agent-ecosystem-war-for-the-developer-terminal/
  15. https://community.openai.com/t/codex-best-practices-for-persistent-secrets/1286607

贡献者

The avatar of contributor named as Xyea Xyea

页面历史