  docs/
    README.md
    development/
      README.md
      architecture.md
      backend.md
      crud.md
      frontend.md
      release.md
  user/
    README.md
    usage.md
    config.md
    deploy.md
    troubleshoot.md
  prompts/
    README.md
    prompt-smart-merge.md
    prompt-proposal-review.md
    prompt-apply-review.md
    prompt-code-review.md

docs/prompts/ 是提示词资产目录，不属于常规开发流程和用户使用文档。代码、配置或部署变更不需要更新该目录，除非任务明确要求维护提示词资产。

入口文档

入口	定位
项目 README	项目整体介绍、快速开始、文档引导
开发文档	开发入口、全部开发规范、常用命令、质量门禁、专题索引
用户文档	使用、配置、部署、排障入口

按任务阅读路径

任务	必读文档
修改项目介绍或快速开始	项目 README、本文档
修改开发流程、质量门禁或工程规则	开发文档、本文档、OpenSpec 配置
修改架构边界或启动流程	开发文档、架构与边界
修改后端 API、配置加载、日志	开发文档、后端开发
修改前端 CRUD 管理页面	开发文档、前端开发、CRUD 模式
修改构建、脚本、发布	构建与发布、部署文档
修改配置 schema	配置文件、后端开发
修改文档规则或文档目录结构	本文档、OpenSpec 配置
首次安装或配置	快速开始、配置文件
排查运行或构建问题	故障排查

文档归属矩阵

变更类型	默认更新位置
项目定位、核心能力、快速开始、顶层文档导航	`README.md`
文档路由、文档更新规则、文档归属矩阵	`docs/README.md`、`openspec/config.yaml`
开发规范（全局规则、库优先级、类型规范、样式、测试等）	`docs/development/README.md`
开发入口、常用命令、质量门禁、目录边界、OpenSpec 约定	`docs/development/README.md`
架构边界、启动流程、运行时流程、前后端边界	`docs/development/architecture.md`
后端模块 API、工具函数索引、数据库 schema、AI 层实现	`docs/development/backend.md`
前端运行时代码结构、组件索引、页面组成、hooks/工具清单	`docs/development/frontend.md`
管理页面 CRUD 模式（筛选工具条、URL 同步、分页排序约定）	`docs/development/crud.md`
构建、发布、脚本、前后端静态资源集成	`docs/development/release.md`
快速开始、安装配置	`docs/user/usage.md`
YAML 配置、变量语法、server/storage/logging、JSON Schema	`docs/user/config.md`
生产构建、可执行文件运行、运行时配置	`docs/user/deploy.md`
常见运行问题、配置校验、变量解析、构建失败	`docs/user/troubleshoot.md`

development 文档如何更新

开发文档解释"如何实现和维护"。代码变更影响开发者理解、开发流程、测试方式或架构边界时，必须更新 docs/development/ 对应文档。

全局规则、常用命令、质量门禁、目录边界、OpenSpec 约定更新到 docs/development/README.md。
全部开发规范（全局规则、后端规范、前端通用规范、样式规范、测试规范）统一维护在 docs/development/README.md。
架构图、启动链路、运行时流程、前后端边界更新到 docs/development/architecture.md。
后端模块 API、工具函数索引、数据库 schema、AI 层实现、日志模块更新到 docs/development/backend.md。
前端运行时代码结构、组件索引、页面组成、hooks/工具清单更新到 docs/development/frontend.md。
构建、脚本和发布验证更新到 docs/development/release.md。
不新增"杂项"开发文档；优先把内容放入上述最贴近的专题，确需新增专题时先更新本文档和 openspec/config.yaml。

user 文档如何更新

用户文档解释"如何使用"和"用户能观察到什么"。变更影响使用方式、配置、部署或运行行为时，必须更新 docs/user/ 对应文档。

安装、配置、快速开始更新到 docs/user/usage.md。
配置结构、变量语法、server/storage/logging 字段更新到 docs/user/config.md。
生产构建、可执行文件运行、运行时依赖更新到 docs/user/deploy.md。
常见错误和排查路径更新到 docs/user/troubleshoot.md。
用户文档避免解释内部实现细节，需要实现细节时链接到 docs/development/。

文档影响分析

每次代码变更都必须执行文档影响分析。

代码或配置变更
  -> 用户能感知吗？更新 docs/user/ 或 README.md
  -> 开发者需要知道吗？更新 docs/development/
  -> 文档规则变化吗？更新 docs/README.md 和 openspec/config.yaml
  -> 都不是？收尾说明写明无需更新文档及原因

同一事实只在最贴近读者的文档中完整展开，其他文档使用链接引用。根目录 README 保持轻量，不承载完整配置参考或实现教程。

收尾说明示例

文档影响分析：本次修改了后端日志配置字段，已更新 docs/development/backend.md 和 docs/user/config.md。

无需更新文档时：

文档影响分析：本次仅调整内部测试 helper，未改变用户可见行为、配置、架构边界或开发流程，因此无需更新文档。

README.md Unescape Escape

Alfred·阿福 文档

目录索引