agilelabs-fx-docs main start/project-structure.md

文档结构与阅读路径

这套文档现在按“任务优先、规则收口、检查独立、主题补充、案例就近、参考收纳”的方式组织，目标是让人和 AI Agent 都能更快定位。

一级目录说明

  • start/：第一次进入站点时先读的内容。
  • tutorials/：按连续上手路径组织的教程主线，适合从零搭建后端和前端骨架。
  • samples/tutorials/：教程配套代码主入口，集中放主线样例和联调/托管说明。
  • tasks/：按“我要做什么”组织，是主阅读入口。
  • framework-standards/：正式规则主入口，集中放必须遵守、推荐做法、默认契约和隐式机制说明。
  • checks/：审查主入口，集中放检查项、判定标准、规则依据和案例对照。
  • topics/：按能力主题组织，集中放原理、实践、扩展方式和主题聚合说明。
  • real-usecases/：真实项目案例总览与项目页面。
  • reference/：低频参考内容，例如包说明、测试、工具、升级。

推荐阅读顺序

  1. 新接入框架：先看 start/，再进入 tasks/。
  2. 想按完整主线从零搭建：进入 tutorials/。
  3. 想先确认教程里的样例最终长什么样：进入 samples/tutorials/。
  4. 要确认正式规则：直接看 framework-standards/。
  5. 要做代码审查或项目巡检：直接看 checks/。
  6. 要理解设计原理和扩展点：再看 topics/。
  7. 要看真实项目：从规则页、检查页或主题页进入 real-usecases/。
  8. 要查包、测试、升级：最后看 reference/。

AI Agent Friendly 规则

  • 路径短且语义单一，尽量避免同一主题分散在多个目录。
  • 文件名统一用 kebab-case。
  • 主阅读路径尽量不超过两级。
  • 正式规则优先放在 framework-standards/，检查项优先放在 checks/。
  • 教程正文优先放在 tutorials/，配套代码优先放在 samples/tutorials/ 并显式链接。
  • 主题页优先做聚合页，而不是把读者丢给多个零散子页。
  • 站点导航以 mkdocs.yml 为唯一来源，兼容页不再承载主正文。

相关页面