# Alfred·阿福 文档

本文档是 Alfred·阿福 的文档路由入口。AI 工具和开发者应先阅读本文件判断本次任务需要读取和更新哪些专题文档，再按任务类型读取最小必要上下文。

## 目录索引

```text
docs/
  README.md
  development/
    README.md
    architecture.md
    backend.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.md)       | 项目整体介绍、快速开始、文档引导       |
| [开发文档](development/README.md) | 开发入口、全局规则、常用命令、质量门禁 |
| [用户文档](user/README.md)        | 使用、配置、部署、排障入口             |

## 按任务阅读路径

| 任务                             | 必读文档                                                                            |
| -------------------------------- | ----------------------------------------------------------------------------------- |
| 修改项目介绍或快速开始           | [项目 README](../README.md)、本文档                                                 |
| 修改开发流程、质量门禁或工程规则 | [开发文档](development/README.md)、本文档、[OpenSpec 配置](../openspec/config.yaml) |
| 修改架构边界或启动流程           | [开发文档](development/README.md)、[架构与边界](development/architecture.md)        |
| 修改后端 API、配置加载、日志     | [开发文档](development/README.md)、[后端开发](development/backend.md)               |
| 修改前端                         | [开发文档](development/README.md)、[前端开发](development/frontend.md)              |
| 修改构建、脚本、发布             | [构建与发布](development/release.md)、[部署文档](user/deploy.md)                    |
| 修改配置 schema                  | [配置文件](user/config.md)、[后端开发](development/backend.md)                      |
| 修改文档规则或文档目录结构       | 本文档、[OpenSpec 配置](../openspec/config.yaml)                                    |
| 首次安装或配置                   | [快速开始](user/usage.md)、[配置文件](user/config.md)                               |
| 排查运行或构建问题               | [故障排查](user/troubleshoot.md)                                                    |

## 文档归属矩阵

| 变更类型                                                  | 默认更新位置                             |
| --------------------------------------------------------- | ---------------------------------------- |
| 项目定位、核心能力、快速开始、顶层文档导航                | `README.md`                              |
| 文档路由、文档更新规则、文档归属矩阵                      | `docs/README.md`、`openspec/config.yaml` |
| 开发入口、常用命令、质量门禁、全局工程规则、OpenSpec 约定 | `docs/development/README.md`             |
| 架构边界、启动流程、运行时流程、前后端边界                | `docs/development/architecture.md`       |
| 后端 API、配置加载、logger、helpers、类型规范、后端测试   | `docs/development/backend.md`            |
| 前端技术栈、组件、样式、数据层、前端测试                  | `docs/development/frontend.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/architecture.md`。
- 后端 API、配置加载、logger、helpers、类型规范和后端测试规范更新到 `docs/development/backend.md`。
- 前端技术栈、组件边界、数据流、样式规则和前端测试规范更新到 `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/`。

## 文档影响分析

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

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

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

## 收尾说明示例

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

无需更新文档时：

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