跳转到内容

AGENTS.md 规格

AGENTS.md 是放置在项目根目录的 AI 指令文件。当 AI 编码工具(Cursor、Claude Code、OpenCode、Codex、ZCode、Qoder、WorkBuddy 等)打开项目时,会读取此文件来理解项目的方法论、规则和工作流。

生成的 AGENTS.md 遵循以下标准模板:

# AI Assistant Instructions
This project follows the **OpenLogos** methodology.
Read `logos/logos-project.yaml` first to understand the project resource index.
## Project Context
- Config: `logos/logos.config.json`
- Resource Index: `logos/logos-project.yaml`
- Tech Stack: [read from logos-project.yaml]
## Methodology Rules
[6 fixed rules — see below]
## Interaction Guidelines
[Phase detection logic + Step 4 batch execution rules]
## Document Edit Verification
[Fixed locale-specific paragraph: after each Markdown/text spec write, re-read from disk and show actual excerpts; no prose-only delivery; typo exception]
## Active Skills
[Dynamically generated based on aiTool setting]
## Change Management
[Varies by lifecycle: initial vs launched]
## Conventions
[Read from logos-project.yaml conventions field]

这些规则在所有 OpenLogos 项目中保持一致,不可自定义:

  1. 在完成设计文档之前绝不写代码
  2. 遵循 Why → What → How 推进
  3. 所有 API 设计必须源自场景时序图
  4. 所有代码变更必须有对应的 API 编排测试
  5. 迭代使用 Delta 变更工作流
  6. 所有生成的测试代码必须包含 OpenLogos reporter(见测试结果格式)
  7. 修改 Markdown 或文本规格后,从磁盘重新读取并向用户展示可验证的原文片段(生成的 Document Edit Verification 章节)

Interaction Guidelines 章节包含阶段检测逻辑,帮助 AI 判断当前项目阶段并建议下一步:

条件建议阶段Skill
prd/1-product-requirements/ 为空Phase 1prd-writer
需求存在,2-product-design/ 为空Phase 2product-designer
设计存在,3-technical-plan/1-architecture/ 为空Phase 3 Step 0architecture-designer
架构存在,2-scenario-implementation/ 为空Phase 3 Step 1scenario-architect
场景存在,api/ 为空Phase 3 Step 2api-designer + db-designer
API 存在,test/ 为空Phase 3 Step 3atest-writer
测试用例存在,scenario/ 为空Phase 3 Step 3btest-orchestrator
以上全部完成Phase 3 Step 4code-implementor
代码存在,verify/ 为空Phase 3 Step 5运行测试 → openlogos verify

launched 项目生成的 Change Management 章节写明 guard 机制、提案流程(change → delta → merge → 代码 → verify → 部署 / smoke → archive → git push)与两档授权,最后列出任何模式(含 openlogos next --auto)都不会自行放行的硬红线:

  • 未收敛代码——gate:implement:loop-exhausted:达到迭代上限仍未通过测试的代码绝不放行。
  • 部署审批与晋级——目标环境要求审批而该版本未获审批,或晋级检查未通过(DEPLOY_APPROVAL_REQUIRED / DEPLOY_PROMOTION_UNVERIFIED)。部署停在「等待审批」或「晋级未满足」,由人审批后重新驱动即可继续。AI 不得自行执行 openlogos approve、不得加 --force-promote、不得换环境或版本、不得改用手工部署或 deploy-done,也不得修改已配置门禁的 logos/environments.yaml 来关闭门禁。

旧版 CLI 生成的项目,升级后执行 openlogos sync 即获得第二条硬红线。

Active Skills 章节根据 logos.config.json 中的 aiTool 字段动态生成:

aiTool 取值Skill 列表来源路径格式
cursor.cursor/skills/*/SKILL.md.cursor/skills/{name}/SKILL.md
claude-codelogos/skills/*/SKILL.mdlogos/skills/{name}/SKILL.md
opencodelogos/skills/*/SKILL.mdlogos/skills/{name}/SKILL.md
codex.agents/plugins/openlogos/skills/*/SKILL.md$openlogos:{name} → .agents/plugins/openlogos/skills/{name}/SKILL.md
zcode.zcode/plugins/openlogos/skills/*/SKILL.md.zcode/plugins/openlogos/skills/{name}/SKILL.md
qoder.qoder/plugins/openlogos/skills/*/SKILL.md.qoder/plugins/openlogos/skills/{name}/SKILL.md
workbuddy.workbuddy/plugins/openlogos/skills/*/SKILL.md.workbuddy/plugins/openlogos/skills/{name}/SKILL.md
otherlogos/skills/*/SKILL.mdlogos/skills/{name}/SKILL.md
all 或数组共享的多工具列表logos/skills/{name}/SKILL.md(只含 Codex 与 Cursor 的数组使用 Codex 格式)

全部 17 个内置 Skill 均带描述列出。

对于 Codex,Active Skills 章节按命名空间分组。OpenLogos 方法论技能展示为 $openlogos:<skill>,并指向 .agents/plugins/openlogos/skills/。项目专属 Skills 保持在 OpenLogos 命名空间之外:项目插件技能使用 .agents/plugins/<plugin>/skills/ 中的 $<plugin>:<skill>,历史或 repo-scoped local Skills 保留在 .agents/skills/ 并归入项目专属分组。

对于 Claude Code,OpenLogos 方法论 Skills 仍位于 logos/skills/;.claude/skills/<skill>/SKILL.md 下的项目技能单独作为项目专属分组保留,不会复制进 OpenLogos 官方插件。

项目只配置了单一宿主时,AGENTS.md 还会附带该宿主的专属段落:

  • Cursor:说明 Skills(.cursor/skills/,显式命令以 /openlogos-<command> 触发)与 change-reviewer subagent 的位置,并带一行固定的 guard 强度说明:Cursor 下写入门禁为部分强度,shell 命令经 beforeShellExecution 事前轻判并经 afterShellExecution 事后检查,文件编辑只经 afterFileEdit 事后报告。OpenLogos 未接入 Cursor 的 preToolUse,因此 Cursor 不会被表述为与 Claude Code 等价。
  • ZCode:直接读取根 AGENTS.md 与插件 Skills,不依赖子目录 AGENTS、include 指令或 CLAUDE.md。
  • Qoder:直接读取根 AGENTS.md 与插件 Skills,关键流程约束不依赖 AGENTS.local.md、.qoder/rules 或其它用户资产。
  • WorkBuddy:方法论上下文来自插件 Skills / 命令与 SessionStart;原生记忆不构成授权,写入权限只由 PreToolUse hook 从磁盘重读项目状态后决定。

对于支持 Skill 绑定的工具(Claude Code、Cursor),阶段检测章节会包含直接文件路径,使 AI 能立即读取并执行 Skill 文件。

AGENTS.md 和 CLAUDE.md 是用户可编辑的文件。OpenLogos 只维护固定 marker 之间的内容:

<!-- OPENLOGOS:BEGIN -->
[OpenLogos generated instructions]
<!-- OPENLOGOS:END -->
  • 文件不存在 → 新建,内容只有托管片段。
  • 已有完整 marker → 只替换 marker 之间的内容,marker 外内容保持原样。
  • 没有 marker,但内容与旧版 OpenLogos 生成模板等价 → 迁移为带 marker 的托管格式。
  • 没有 marker,且有你自己的内容 → 保留原文,在文件末尾追加托管片段。
  • marker 不完整(只有 begin 或只有 end)→ 写入直接报错;请修复或备份文件后重试。
  • 已存在 agents.md、Claude.md 等大小写变体时,复用该文件,不会另建第二份。
章节来源
Tech Stacklogos-project.yaml → tech_stack
Active Skillslogos.config.json → aiTool + 已部署 Skill 扫描
Conventionslogos-project.yaml → conventions
Methodology Rules固定内容(不可自定义)
事件触发条件
openlogos init项目初始化时首次生成
openlogos init --ai-tool <tool>为已初始化项目补齐目标工具后刷新
openlogos adopt接入已有代码库时生成(launched 规则)
openlogos sync升级 CLI 或项目配置变更后重新生成
openlogos launch切换到 launched 变更管理规则后刷新
project-init SkillAI 发起的项目初始化

所有入口都使用同一套托管片段合并逻辑,marker 之外的内容始终保留。

不同 AI 工具使用不同的指令文件名,但内容一致:

工具指令文件Skill 位置部署
CursorAGENTS.md(原生支持).cursor/skills/<name>/SKILL.md(原生 Agent Skills,另含命令 Skills 与 change-reviewer subagent)init / sync 部署 Skills,并向 .cursor/hooks.json 合并托管条目;你自己的 Skills、rules 与 hook 条目保留。见 Cursor 插件
Claude CodeCLAUDE.mdlogos/skills/*/SKILL.md由 init / sync 自动部署
OpenCode(兼容)AGENTS.mdlogos/skills/*/SKILL.md由 init / sync 自动部署
OpenCode(插件)opencode.json + .opencode/plugins/插件加载插件处理命令桥接,AGENTS.md 作为回退
CodexAGENTS.md + .codex/config.toml + .agents/plugins/marketplace.json$openlogos:<skill> 使用 .agents/plugins/openlogos/skills/*;项目插件或 .agents/skills/* 单独保留init / sync 只刷新 marketplace 的 openlogos 条目并保留项目 Skills
ZCode根 AGENTS.md.zcode/plugins/openlogos/skills/init / adopt / sync / launch 安装插件;不修改 .zcode/config.json。见 ZCode 插件
Qoder根 AGENTS.md(Qoder CLI 静态记忆).qoder/plugins/openlogos/skills/init / adopt / sync / launch 安装插件;不修改 AGENTS.local.md、.qoder/rules/ 与 Qoder 设置。见 Qoder 插件
WorkBuddy根 AGENTS.md.workbuddy/plugins/openlogos/skills/init / adopt / sync / launch 安装插件;不修改 WorkBuddy 设置,不读写原生记忆。见 WorkBuddy 插件
GitHub Copilot.github/copilot-instructions.md计划中未来版本

openlogos sync 会同时生成所有需要的指令文件,确保各 AI 工具间指令一致。

文件格式受众内容
logos-project.yaml结构化 YAMLAI + 工具资源索引、技术栈、约定
AGENTS.md自然语言 MarkdownAI 助手行为指令、规则、Skill 列表

二者互补:AGENTS.md 指引 AI 去读 logos-project.yaml;logos-project.yaml 为 AI 提供可消费的结构化数据。