项目架构文档包
目的
每个项目都应该有一组最小架构文档，先让新人、接手项目的人和技术负责人能回答：
这个项目解决什么问题？
用什么技术栈？
系统怎么分层？
有哪些模块和服务？
上游依赖谁？
下游影响谁？
数据在哪里？
API 和事件怎么交互？
怎么本地运行、测试、部署、回滚？
哪些地方不能随便改？
没有这些文档，人类 review 只能依赖资深工程师记忆；后续 Agent 也只能靠代码搜索和猜测工作。
最小文档包
| 文件 | 必须回答 | 模板 |
|---|---|---|
docs/PROJECT.md |
项目入口、owner、环境、命令、监控、发布和回滚入口 | templates/项目入口-project-index.md |
docs/ARCHITECTURE.md |
系统边界、架构图、模块、数据流、运行路径 | templates/系统架构-architecture.md |
docs/TECH_STACK.md |
技术选型、版本、替代方案、选型原因 | templates/技术选型-tech-stack.md |
docs/DEPENDENCIES.md |
上游、下游、外部服务、失败影响、owner | templates/依赖图-dependency-map.md |
docs/MODULE_CONTRACTS.md |
模块职责、接口、数据、依赖、禁止耦合 | templates/模块契约-module-contract.md |
docs/SERVICE_CONTRACTS.md |
服务 API、鉴权、事件、SLO、运维入口 | templates/服务契约-service-contract.md |
docs/TESTING.md |
每种变更应该跑什么检查，命令语义是什么 | 33-测试和质量-testing-quality.md |
docs/RUNBOOK.md |
生产故障如何诊断、缓解、回滚 | templates/运维手册-runbook.md |
docs/SECURITY.md |
鉴权、密钥、权限、数据敏感性、安全 review | 55-安全基线-security-baseline.md |
草台团队可以先只做四个：
PROJECT.md
ARCHITECTURE.md
TECH_STACK.md
DEPENDENCIES.md
这四个能让新人快速知道项目入口、项目边界、技术栈和上下游风险。
L0 要求：PROJECT.md 必须能让新人找到 owner、启动命令、检查命令、监控、发布和回滚入口；其他文档每份最多一页，先回答关键问题，不追求完整格式。等项目稳定后再补模块契约、服务契约、runbook 和安全文档。
项目级落地要求见 40-项目级闭环-project-level-closure.md。
三角色项目文档责任
| 角色 | 对项目文档负责什么 |
|---|---|
| 产品负责人 | PROJECT.md 中的用户、核心路径、业务 owner、验收入口 |
| 技术负责人 | ARCHITECTURE.md、模块边界、数据、风险路径 |
| 平台 / 资深工程师 | TECH_STACK.md、DEPENDENCIES.md、本地运行、CI、发布和排障入口 |
架构文档必须覆盖
1. 系统边界
说明这个项目做什么、不做什么、谁使用、谁维护。
2. 技术选型
说明语言、框架、数据库、队列、缓存、部署方式、测试工具、观测工具，以及为什么选它们。
3. 模块和服务
说明每个模块或服务的职责、owner、输入输出、拥有的数据、禁止耦合。
4. 上下游依赖
说明：
| 方向 | 要记录什么 |
|---|---|
| 上游 | 谁调用本系统，依赖哪些 API、事件、SLA |
| 下游 | 本系统调用谁，失败后怎么降级 |
| 外部服务 | 第三方 API、provider、支付、短信、对象存储等 |
| 共享基础设施 | DB、Redis、queue、object storage、feature flag、secret manager |
5. 数据和状态
说明核心表、状态机、数据 owner、保留策略、migration 入口。
6. API / 事件契约
说明 REST/RPC/webhook/event 的 schema、鉴权、幂等、错误码、版本兼容。
7. 运行和部署
说明本地启动、CI 检查、部署流程、环境变量、回滚路径。
8. 项目 Owner 和入口
说明 Product Owner、Tech Owner、Ops Owner、Doc Driver、任务看板、PR/CI、监控、日志、发布入口在哪里。
9. 风险边界
说明哪些路径、表、权限、集成、生产配置必须人工 approval。
后续 Agent 使用方式
这一节在人类架构文档包稳定后再看。
Agent run 启动前，应优先读取：
ARCHITECTURE.mdTECH_STACK.mdDEPENDENCIES.md- 相关
MODULE_CONTRACTS.md或SERVICE_CONTRACTS.md TESTING.md
如果这些文档缺失，Agent 应先执行 discovery，输出架构草稿或依赖清单，而不是直接改代码。
更新规则
这些变化必须同步更新架构文档包：
- 新增或删除服务。
- 模块职责变化。
- 数据库 schema 或核心状态机变化。
- 新增上游或下游依赖。
- 外部 API、webhook、事件契约变化。
- 部署方式、环境变量、密钥策略变化。
- 自动化或 Agent runtime、权限、scope 或 approval 策略变化。
如果 PR 改了架构但没有更新文档，reviewer 应要求补齐。
过期规则
架构文档不是一次性产物。
| 规则 | 处理方式 |
|---|---|
| 超过 30 天未确认 | Driver 快速检查是否仍准确 |
| 超过 60 天未确认 | 标记 stale，不作为默认事实 |
| 文档和代码冲突 | 以代码和运行事实为准，同时创建文档修复任务 |
| Agent 发现冲突 | 先输出差异和建议，不直接按过期文档改代码 |
每个项目至少指定一个 Doc Driver，负责推动架构文档不过期。Doc Driver 不一定亲自写完，但要负责让文档能被信任。
下一步阅读
读完或填完这份文档后，通常继续看：
- 项目入口-project-index.md：落到具体项目时，先填项目入口模板。
- 43-本地开发-local-development.md：再确认本地运行和开发环境。