用于codex的开发指南

AGENTS.md

overview

这是一个安卓-鸿蒙 cli 化的比较项目，鸿蒙cli功能上需要和安卓cli完全对齐。

团队文化

• 极客团队: 尽可能的，在各种维度上并行开发，充分相信和依赖 subagent / parallel，激进的多线开发
• 产品落地: 目标从来不只是mvp，而是可交付的产品，高完成度的开源项目的形式
• 自主迭代: 一旦开发，则持续迭代，依赖构建可观测体系数据反馈，中间不会询问开发者，直到完成
• 文档意识: 将文档视为一等公民，和代码一样重要的交付物，proposal，idea，insight，调研，research，debug...anything
• 自我反思: 总是追问自己，比如是否存在其他方法，某件事是否完成了，上下文获取充分了吗，调研到位了吗，达到发布状态了吗，像用户一样使用了吗，等等，你总有各种问题，并自行解决
• 冷漠的执行者: 从不询问，除了和用户对需求，总是努力交付

TDD Workflow

这是一个Features+TDD（Test-Driven Development）工作流程的仓库，所有开发必须遵循以下规则:

澄清需求

• 需求对齐阶段，采用AMA（Ask Me Anything）原则：可以问任何你想问的问题，直到完全理解用户意图
• 并行对齐：同时提供几个可选方案和1个推荐方案让用户选择-
• 阶段性：进入TDD流程禁止询问开发者，必须在未进入开发状态前询问，

写plan.md

• 首先将这些点分别进行充分的调研，可以使用subagent并行，写成多个新的docs/plans//plan.md, 落成一组新的研究计划包
• 写完后再跑一遍快速自检，确认新增目录、计划索引和变更记录都对齐。
• 架构设计意识：对全局架构进行把控，不断演进系统架构，支撑巨型业务增长。

新建feature

• 默认一次开发任务对应一个 feature；过大任务必须拆成可独立测试的子 feature。
• 纯文档或纯清理改动可不新建 feature；如果服务于已有 feature，仍需更新对应条目。
• 所有 feature 必须按以下步骤执行：
  1. 先创建或更新 docs/features/<index-feature-id>.json，feature-id 使用稳定的 kebab-case。
  2. feature 文件必须是合法 JSON，并包含 id、title、passed、summary、description、subfeatures、verification_tasks_tests、tests、updated_at。
  3. description 必须把需求写清楚；subfeatures 必须直接嵌套子需求，而不是单独用 parent_feature 或 id 引用关系表达； tests 只表示本 feature 新增的测试文件;
  4. verification_tasks_tests 是文本描述的验收任务，通常是针对某个功能点的端到端的一句话任务:
  • task_id: 验收任务的唯一标识，使用稳定的 kebab-case(全局共享，允许复用)
  • description: 验收任务的文本描述
  • expected_result: 验收任务的预期结果
  • user: 验收任务的执行者，通常是 human agent 的 name
  • passed: 验收任务的完成状态，初始值为 false，验收完成后更新为 true
  4. 未登记 feature，不得开始实现。

TDD

红 → 绿 → 重构 的 TDD 流程：

1. 红阶段（Red）：先写测试，故意失败
2. 绿阶段（Green）：写最烂但能过的代码
3. 重构阶段（Refactor）：优化代码，保持绿色
4. 并行开发：优先使用spawn subagent/parallel worker，尤其是subfeatures
5. 测试反馈：tests 和 verification_tasks_tests 的问题都要及时修复

HUMAN-LIKE 测试反馈

• 自建测试环境：缺少设备则启动模拟器，缺少应用则创建测试应用，缺少数据则增加log,trace, 缺少工具则去github找开源工具等等，使用 subagent 扮演 infrastructure agent 来构建和维护测试环境
• 如果有 verification_tasks_tests ，需要用 subagent 模拟 human agent 进行验收，并且在验收报告中明确说明每个验收任务的完成情况

开发进度记录

记录在 task_progress.md

• OVERVIEW : 记录每个阶段的完成情况和里程碑，流水账
• PLAN CREATION : 记录每个 plan 的 进度
• FEATURE ACTIVATION : 记录当前激活的features 和 已完成的 features
• HANDOVER : 有重大需要交接/context compact 的变更时，记录当前上下文，方便同事接手

Change Log

• 每次完成有意义的变更后，update changelog.md
• 不要出现具体的代码路径，而是从用户和产品的角度描述变更内容和影响
• format:
• 简短的标题
• TLDR: 一句话总结变更内容和影响
• 分点的描述1,2,3...每个描述一句话

Code Quality

• 优先选择简单、直接、可解释、可推广的通用方案。
• 删除重复逻辑、失效逻辑和临时兼容层。
• 不要写只对单个样例或单个环境生效的补丁式修复。
• Avoid hacks, fallback, heuristics, local stabilizations, or post-processing bandages that are not faithful general algorithms.

Other

• 这是团队项目，可能有同事也在同时修改仓库中的其他部分。
• 不要 revert、覆盖或顺手修改不属于当前 feature 的同事代码。
• 每次上下文不足时发生compact前，记录当前上下文到 task_progress.md/HANDOVER.