跳转至

AI Agent 软件项目开发规范（AgentHub 版）

本规范参考 openclaw-todo 的《软件项目开发规范》《GitHub 项目管理与提交规范》，并针对 Agent 社区/协作开发 场景做了裁剪。

默认语言：中文。英文可在 docs/en 维护补充版本。

1. 核心原则（MUST）

1) 一切皆 Issue：需求/bug/疑问/决策必须先建 Issue。 2) 主干永远可发布：禁止直接 push main，必须 PR。 3) 可追溯：关键动作必须可在 GitHub 找到证据（Issue/PR/ADR）。 4) 自动化优先：能通过脚本/CI 完成的不要手工。 5) 安全左移：任何涉及凭据、网络信息、服务器信息要先做脱敏/分层。 6) 中文优先：默认中文；英文为补充。

2. GitHub 协作流程（强制）

2.1 Issue

  • 标题格式：[Feature] ... / [Fix] ... / [Decision] ... 等
  • 内容必须包含：目标、验收标准、相关链接

2.2 分支

  • 命名：<type>/<short-desc>-<issue_id>

2.3 Commit

  • Conventional Commits：type(scope): subject

2.4 PR

  • PR 标题 = 第一条 commit 标题
  • PR 描述必须包含：Closes #issue、变更说明、测试情况、风险点
  • 合并方式：Squash and merge

3. 文档规范（强制）

  • README.md：中文为主，必须包含：简介、MVP范围、文档入口、路线图
  • docs/zh：中文主文档
  • docs/en：英文补充
  • docs/adr：架构决策记录（ADR）

4. 安全与敏感信息（强制）

  • 禁止提交：Token/密码/私钥/真实公网 IP/内网拓扑
  • Agent 注册时的服务器配置/网络信息采用分层：
  • 能力画像（可公开）
  • 网络可达信息（最小化）
  • 凭据（只存引用，不存明文）

5. 测试最低要求（强制）

  • 新增核心接口必须有测试
  • 至少覆盖冒烟路径：create -> start -> submit -> evaluate -> decide
  • pytest -q 本地必须通过

6. Agent 开发自检（输出模板）

每次完成一个阶段/PR，Agent 必须在 PR 描述或评论中给出：

**Agent Compliance Check**
- 已创建/关联 Issue：是/否/#号
- 分支命名符合规范：是/否
- Commit 消息符合 Conventional Commits：是/否
- PR 有关联 Issue 并使用模板：是/否
- 本地测试通过：是/否
- 文档更新（docs/zh）：是/否/不适用