project-docs

项目文档

为长期维护的仓库建立简洁、可追溯的项目级文档。项目文档记录稳定上下文，不替代功能规格：功能规格仍属于 docs/specs/。

先审计，后写入。没有用户对建议范围的明确确认时，不创建或修改任何文件。

审计

在仓库中只读检查以下证据：

• README.md、AGENTS.md、docs/ 及其他现有说明文档。
• 目录结构、主要模块边界和测试位置。
• 已验证或可从配置确认的启动、构建、测试和检查命令。
• 包管理器、运行时、部署配置与外部服务集成。
• 一段有代表性的近期 Git 历史，以识别活跃区域和文档可能过时的风险。

不要把缺失的信息补成猜测。Git 历史不可用或证据不足时，明确说明限制。

输出一份简短的“文档审计与建议”，包含：

## 文档审计与建议

**检查过的证据：** <关键文件、配置、测试和近期变更>

**证据限制：** <如有>

### 已有文档

- `<路径>`：<用途、可见缺口或可能过时的风险>

### 建议创建

- [ ] `<路径>`：<为什么此仓库现在需要它>

### 建议跳过

- `<路径>`：<为什么现在创建会重复或缺少可靠事实>

默认建议缺失的 README.md 和 AGENTS.md。仅当项目具有明确用户价值、多个核心能力或长期产品边界时，建议 docs/PRODUCT.md。仅当项目存在多个模块、服务、关键集成或不直观的数据流时，建议 docs/ARCHITECTURE.md。

已有文档默认只报告，不改写。等待用户确认、移除或增加建议中的文件后，才继续。

创建规则

只创建用户确认且当前缺失的文件。每份文档使用中文，保留命令、路径、代码标识符和产品专有名词的原样拼写。

所有内容必须能够追溯到代码、配置、测试、已有文档或用户确认。事实无法确认时，省略该内容，并在最终交付中说明缺口。不要为凑模板保留空章节。

README.md

面向人类读者，只包含项目用途、必要前置条件和已验证的快速开始命令。

不得放入 AI 操作规则、常用命令索引、详细架构叙述、功能规格、文档导航或变更日志。控制在约 40 行以内，只保留首次使用项目所必需的信息。

按需使用以下最小结构：

# <项目名称>

<一句话说明项目用途。>

## 快速开始

<前置条件与已验证命令。>

AGENTS.md

面向执行 AI，只包含仓库地图、已验证命令、代码与测试约定、安全边界和容易误触的区域。

不得复述项目目的、用户需求、完整架构、功能规格或历史决策。控制在约 80 行以内，使用短路径说明和命令块，不写教程。

按需使用以下最小结构：

# AGENTS.md

## 仓库地图

<重要路径及职责。>

## 验证命令

<已验证的测试、检查和构建命令。>

## 约定与边界

<代码、测试、安全或易误触区域的约束。>

docs/PRODUCT.md

记录稳定的产品上下文：目标用户、要解决的问题、核心能力和明确非目标。

不得放入实现路径、文件列表、临时功能状态或具体任务验收。控制在约 120 行以内，按问题和用户价值组织。

按需使用以下最小结构：

# 产品说明

## 用户与问题

<服务对象及其持续存在的问题。>

## 核心能力

<稳定且用户可感知的能力。>

## 非目标

<明确不解决的问题或不承诺的能力。>

docs/ARCHITECTURE.md

记录稳定技术结构：系统边界、核心模块职责、重要依赖、关键数据或调用流，以及架构约束。

不得复制目录树、API 细节、配置清单、实现步骤或历史变更。控制在约 160 行以内。只有关系或流程用文字难以说明时，才使用一张 Mermaid 图。

按需使用以下最小结构：

# 架构说明

## 系统边界

<系统负责什么，以及重要的外部边界。>

## 核心组成

<模块或服务的职责和主要边界。>

## 关键流程

<最重要的数据或调用流。>

## 架构约束

<必须维持的边界、兼容性或运行约束。>

只有具备可靠内容时才保留模板章节。如果信息超过篇幅上限，压缩为边界、职责和链接，而不是继续堆叠细节。

结束

完成后报告创建的路径、每份文档的用途和未覆盖的事实缺口。不要创建功能 spec、任务票、架构评审报告或代码变更，也不要自动实施文档中提到的后续工作。