AI Agent — 文档组织结构说明

本文档面向参与项目开发的 AI Agent，说明项目的文档组织结构，以便 Agent 正确理解和操作项目文档。

---

文档组织结构

层级关系

docs/ai-agent/
├── index.md                        ← 本文档：文档组织结构说明
├── skills/                         ← AI 技能库（跨版本通用）
│   └── index.md                    ← 技能库索引
└── v4/                             ← v4 主线版本开发文档
    ├── index.md                    ← 版本文档索引
    ├── design/                     ← 架构/功能设计文档
    ├── plans/                      ← 开发计划文档
    ├── tests/                      ← 测试文档
    ├── discussions/                ← 讨论记录文档
    ├── logs/                       ← 开发日志
    └── bugs/                       ← 缺陷修复文档

文档类型与规范

文档类型	目录	更新策略	说明
AI 技能库	skills/	持续更新	跨版本通用的最佳实践和规范
设计文档	v4/design/	持续更新	保持最新，清理过时内容
测试文档	v4/tests/	持续更新	只有软件验收员才能编写和更新测试用例
计划文档	v4/plans/	持续更新	保持最新，清理已完成 / 过时内容
讨论记录	v4/discussions/	只追加	历史记录，不对已有内容做更新
开发日志	v4/logs/	只追加	历史记录，不对已有内容做更新
缺陷修复	v4/bugs/	只追加	历史记录，不对已有内容做更新

文件命名规范

• design/、plans/、discussions/ 目录下的文档以 三位数字 开头并根据内容确定文件名
  • 示例：000-architecture-overview.md、100-keyboard-state-machine.md
• logs/ 目录下的文档按 年 组织子目录，以 月-日 命名（月和日采用两位数字）
  • 示例：2026/05-12.md
• bugs/ 目录下的文档以 三位数字 开头和缺陷简要描述命名
  • 示例：001-input-list-concurrent-modification.md

文档编写规范

详见 文档编写规范，涵盖中英文间距、PlantUML 语法注意事项、Markdown 语法注意事项等。

---

参考工作树

工作树	分支	用途
kotlin/	refactor-kotlin	工作目录：Kotlin 版本的开发在此进行
java/	java-frozen	只读参考：Java 版本代码，仅在需要时查阅

重要：java/ 工作树为只读，仅用于在需要时查阅 Java 版本的代码。不要修改 java 工作树中的任何文件。