项目约定手册

概述

项目约定手册（AGENTS.md）是 Ralph Loop 系统中由 Agent 自动维护的经验文档，记录项目概览、运行命令、文件结构、命名规范、代码约定、禁止事项和环境变量。

关键内容

1. 定位：每次 Ralph 会话开始时必读的文件，由 Agent 在运行过程中自动更新，保持精简（每增加 1k tokens 都减少 Agent 有效工作空间）。
2. 项目概览：记录项目名称、技术栈、开发服务器地址、创建日期。
3. 运行命令：启动脚本（init.sh）、开发服务器、构建命令、类型检查、数据库迁移、测试运行、验证脚本。
4. 文件结构约定：Next.js App Router 目录结构（app/、components/、lib/、types/、hooks/）、Prisma 数据库模型目录。
5. 命名规范：React 组件 PascalCase、工具函数 camelCase、API 路由 kebab-case、数据库模型 PascalCase 单数、测试文件同名 + .test。
6. 代码约定：默认使用 Server Components，Client Components 仅在需要时添加；API 路由使用 Route Handlers；统一错误处理模式。
7. 禁止事项（NEVER DO）：不删除已通过测试；不未验证就设 passes: true；不提交 build 失败的代码；不留下半完成功能未 commit；不修改 prd.json 的 acceptanceCriteria；不跳过启动序列；不硬编码密钥。
8. 自动填充区域：Known Issues & Gotchas、Learnings from Previous Sessions、Dependency Map 由 Agent 在运行过程中自动填充。

来源

• raw/articles/ai-tools/ralph-loop/AGENTS.md — 完整模板
• raw/articles/ai-tools/ralph-loop/coding-agent.md — Agent 协议中引用

相关

• Ralph Loop 系统 — part_of
• 编码 Agent 协议 — used_by