标准化 MD 文件清单
这份清单适合前后端项目初始化时使用。可以先创建“最小可用版”，再随着项目成熟逐步补齐。
项目入口
| 文件 | 必要性 | 说明 |
|---|---|---|
README.md | 必须 | 项目介绍、快速启动、核心命令 |
CHANGELOG.md | 推荐 | 版本变更记录 |
CONTRIBUTING.md | 推荐 | 分支、提交、PR、审查流程 |
SECURITY.md | 推荐 | 漏洞报告、安全边界 |
LICENSE.md | 视情况 | 开源或内部授权说明 |
产品与需求
| 文件 | 必要性 | 说明 |
|---|---|---|
docs/product/PRD.md | 必须 | 产品目标、范围、验收标准 |
docs/product/USER_STORIES.md | 推荐 | 用户故事和场景 |
docs/product/ROADMAP.md | 推荐 | 版本规划 |
架构与接口
| 文件 | 必要性 | 说明 |
|---|---|---|
docs/architecture/OVERVIEW.md | 必须 | 系统总览、模块关系 |
docs/architecture/FRONTEND.md | 必须 | 前端架构、状态管理、路由 |
docs/architecture/BACKEND.md | 必须 | 后端架构、模块边界 |
docs/architecture/DATABASE.md | 推荐 | 数据模型、迁移策略 |
docs/architecture/ADR/ | 推荐 | 架构决策记录 |
docs/api/API_SPEC.md | 必须 | API 路径、请求、响应 |
docs/api/ERROR_CODES.md | 推荐 | 错误码和错误格式 |
docs/api/AUTH.md | 推荐 | 鉴权与权限模型 |
开发与质量
| 文件 | 必要性 | 说明 |
|---|---|---|
docs/development/SETUP.md | 必须 | 本地环境和启动步骤 |
docs/development/CODING_STANDARDS.md | 必须 | 代码风格和目录约定 |
docs/development/BRANCHING.md | 推荐 | 分支策略 |
docs/development/REVIEW_CHECKLIST.md | 推荐 | PR 审查清单 |
docs/testing/TEST_STRATEGY.md | 必须 | 测试分层和运行方式 |
docs/testing/E2E.md | 推荐 | 端到端测试策略 |
运维与 AI 协作
| 文件 | 必要性 | 说明 |
|---|---|---|
docs/operations/DEPLOYMENT.md | 必须 | 部署步骤和回滚 |
docs/operations/ENVIRONMENT.md | 必须 | 环境变量和配置 |
docs/operations/OBSERVABILITY.md | 推荐 | 日志、指标、告警 |
docs/operations/RUNBOOK.md | 推荐 | 常见故障处理 |
CLAUDE.md | Claude 项目必须 | Claude Code 项目指令 |
AGENTS.md | Codex 项目必须 | Codex 项目指令 |
docs/ai/PROMPTING.md | 推荐 | 团队提示模板 |
docs/ai/AI_REVIEW.md | 推荐 | AI 辅助审查规范 |
初始化顺序
- 先写
README.md、SETUP.md、PRD.md。 - 再写
OVERVIEW.md、API_SPEC.md、CODING_STANDARDS.md。 - 然后写
TEST_STRATEGY.md、DEPLOYMENT.md、ENVIRONMENT.md。 - 最后根据使用工具补
CLAUDE.md或AGENTS.md。