# AIOX 方法指导原则 > 🌐 [EN](../GUIDING-PRINCIPLES.md) | [PT](../pt/GUIDING-PRINCIPLES.md) | [ES](../es/GUIDING-PRINCIPLES.md) | **ZH** --- AIOX 方法是一个用于 AI 辅助软件开发的自然语言框架。这些原则确保贡献保持该方法的有效性。 ## 核心原则 ### 1. 开发代理必须精简 - **最小化开发代理依赖**：在 IDE 中工作的开发代理必须有最小的上下文开销 - **为代码节省上下文**：每一行都很重要 - 开发代理应专注于编码，而不是文档 - **Web 代理可以更大**：在 Web UI 中使用的规划代理（PRD 编写者、架构师）可以有更复杂的任务和依赖 - **小文件，按需加载**：多个小的专注文件比包含许多分支的大文件更好 ### 2. 自然语言优先 - **一切都是 markdown**：代理、任务、模板 - 全部用简单英文编写 - **核心中没有代码**：框架本身不包含任何编程代码，只有自然语言指令 - **自包含的模板**：模板定义为 YAML 文件，具有结构化章节，包括元数据、工作流程配置和详细的内容生成说明 ### 3. 代理和任务设计 - **代理定义角色**：每个代理是具有特定专业知识的人物角色（例如前端开发人员、API 开发人员） - **任务是程序**：代理遵循的逐步说明来完成工作 - **模板是输出**：具有嵌入式内容生成说明的结构化文档 - **依赖很重要**：明确仅声明所需的内容 ## 实践指南 ### 何时添加到核心 - 仅通用软件开发需求 - 不会膨胀开发代理上下文 - 遵循现有代理/任务/模板模式 ### 何时创建 Squads - 超越软件开发的特定领域需求 - 非技术领域（商业、健康、教育、创意） - 专门的技术领域（游戏、基础设施、移动） - 大量文档或知识库 - 任何会膨胀核心代理的东西 查看 [Squads 概述](./guides/squads-overview.md) 了解详细示例和想法。 ### 代理设计规则 1. **Web/规划代理**：可以有更丰富的上下文、多个任务、广泛的模板 2. **开发代理**：最少的依赖，专注于代码生成，精简任务集 3. **所有代理**：清晰的人物角色、具体的专业知识、定义明确的能力 ### 任务编写规则 1. 编写清晰的逐步程序 2. 使用 markdown 格式提高可读性 3. 保持开发代理任务专注且简洁 4. 规划任务可以更详细 5. **优先选择多个小任务而不是一个大的分支任务** - 不是一个包含许多条件路径的任务 - 创建多个专注的任务代理可以选择 - 这保持上下文开销最小 6. **重用常见任务** - 不要创建新的文档创建任务 - 使用现有的 `create-doc` 任务 - 传递具有结构化章节的适当 YAML 模板 - 这保持一致性并减少重复 ### 模板规则 模板遵循 [AIOX 文档模板](../common/utils/aiox-doc-template.md) 规范，使用 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 处理专门领域