Skip to content

GUIDING-PRINCIPLES.md

Latest commit

 

History

History
97 lines (71 loc) · 4.07 KB

GUIDING-PRINCIPLES.md

File metadata and controls

97 lines (71 loc) · 4.07 KB

AIOX 方法指导原则

🌐 EN | PT | ES | ZH

AIOX 方法是一个用于 AI 辅助软件开发的自然语言框架。这些原则确保贡献保持该方法的有效性。

核心原则

1. 开发代理必须精简

  • 最小化开发代理依赖：在 IDE 中工作的开发代理必须有最小的上下文开销
  • 为代码节省上下文：每一行都很重要 - 开发代理应专注于编码，而不是文档
  • Web 代理可以更大：在 Web UI 中使用的规划代理（PRD 编写者、架构师）可以有更复杂的任务和依赖
  • 小文件，按需加载：多个小的专注文件比包含许多分支的大文件更好

2. 自然语言优先

  • 一切都是 markdown：代理、任务、模板 - 全部用简单英文编写
  • 核心中没有代码：框架本身不包含任何编程代码，只有自然语言指令
  • 自包含的模板：模板定义为 YAML 文件，具有结构化章节，包括元数据、工作流程配置和详细的内容生成说明

3. 代理和任务设计

  • 代理定义角色：每个代理是具有特定专业知识的人物角色（例如前端开发人员、API 开发人员）
  • 任务是程序：代理遵循的逐步说明来完成工作
  • 模板是输出：具有嵌入式内容生成说明的结构化文档
  • 依赖很重要：明确仅声明所需的内容

实践指南

何时添加到核心

  • 仅通用软件开发需求
  • 不会膨胀开发代理上下文
  • 遵循现有代理/任务/模板模式

何时创建 Squads

  • 超越软件开发的特定领域需求
  • 非技术领域（商业、健康、教育、创意）
  • 专门的技术领域（游戏、基础设施、移动）
  • 大量文档或知识库
  • 任何会膨胀核心代理的东西

查看 Squads 概述 了解详细示例和想法。

代理设计规则

  1. Web/规划代理：可以有更丰富的上下文、多个任务、广泛的模板
  2. 开发代理：最少的依赖，专注于代码生成，精简任务集
  3. 所有代理：清晰的人物角色、具体的专业知识、定义明确的能力

任务编写规则

  1. 编写清晰的逐步程序
  2. 使用 markdown 格式提高可读性
  3. 保持开发代理任务专注且简洁
  4. 规划任务可以更详细
  5. 优先选择多个小任务而不是一个大的分支任务
    • 不是一个包含许多条件路径的任务
    • 创建多个专注的任务代理可以选择
    • 这保持上下文开销最小
  6. 重用常见任务 - 不要创建新的文档创建任务
    • 使用现有的 create-doc 任务
    • 传递具有结构化章节的适当 YAML 模板
    • 这保持一致性并减少重复

模板规则

模板遵循 AIOX 文档模板 规范，使用 YAML 格式：

  1. 结构：模板在 YAML 中定义，具有清晰的元数据、工作流程配置和章节层次结构
  2. 关注点分离：LLM 的说明在 instruction 字段中，与内容分离
  3. 可重用性：模板是代理不可知的，可以跨不同代理使用
  4. 关键组件：
    • 元数据的 template 块（id、name、version、output settings）
    • 交互模式配置的 workflow 块
    • 定义文档结构的 sections 数组及其嵌套子章节
    • 每个章节都有 id、title 和 instruction 字段
  5. 高级功能：
    • 使用 {{variable_name}} 语法进行变量替换
    • 使用 condition 字段的条件章节
    • 使用 repeatable: true 的可重复章节
    • 使用 owner 和 editors 字段的代理权限
    • 示例数组用于指导（永远不包含在输出中）
  6. 清晰的输出：YAML 结构确保所有处理逻辑与生成的内容分离

记住

  • 力量在于自然语言编排，而不是代码
  • 开发代理编码，规划代理规划
  • 保持开发代理精简以获得最大编码效率
  • 启动 squads 处理专门领域