Vibe Coding 知识库

前后端项目标准化 MD 文件集 ​

一个成熟的前后端开发项目，最好把“需求、架构、接口、开发约定、测试、部署、AI 协作规则”都沉淀成 Markdown 文件。这样团队成员、AI 编程助手、CI/CD 和代码审查流程都能围绕同一套事实工作。

本主题给出两套示例：

  • Claude 版：以 CLAUDE.md、Claude Code 工作流、命令和记忆文件为中心。
  • Codex 版：以 AGENTS.md、Codex 配置、提示工作流和安全边界为中心。

推荐目录结构 ​

text
project-root/
├── README.md
├── CHANGELOG.md
├── CONTRIBUTING.md
├── SECURITY.md
├── LICENSE.md
├── docs/
│   ├── product/
│   │   ├── PRD.md
│   │   ├── USER_STORIES.md
│   │   └── ROADMAP.md
│   ├── architecture/
│   │   ├── OVERVIEW.md
│   │   ├── FRONTEND.md
│   │   ├── BACKEND.md
│   │   ├── DATABASE.md
│   │   └── ADR/
│   ├── api/
│   │   ├── API_SPEC.md
│   │   ├── ERROR_CODES.md
│   │   └── AUTH.md
│   ├── development/
│   │   ├── SETUP.md
│   │   ├── CODING_STANDARDS.md
│   │   ├── BRANCHING.md
│   │   └── REVIEW_CHECKLIST.md
│   ├── testing/
│   │   ├── TEST_STRATEGY.md
│   │   ├── E2E.md
│   │   └── TEST_DATA.md
│   ├── operations/
│   │   ├── DEPLOYMENT.md
│   │   ├── ENVIRONMENT.md
│   │   ├── OBSERVABILITY.md
│   │   └── RUNBOOK.md
│   └── ai/
│       ├── PROMPTING.md
│       ├── AI_REVIEW.md
│       └── TASK_TEMPLATES.md
└── .github/
    └── PULL_REQUEST_TEMPLATE.md

文件分层 ​

层级目标代表文件
项目入口让新人和 AI 快速理解项目README.md、SETUP.md
产品事实明确做什么、不做什么PRD.md、USER_STORIES.md、ROADMAP.md
技术事实明确系统如何组成OVERVIEW.md、FRONTEND.md、BACKEND.md、DATABASE.md
协作规范明确如何开发和审查CONTRIBUTING.md、CODING_STANDARDS.md、REVIEW_CHECKLIST.md
质量保障明确如何验证TEST_STRATEGY.md、E2E.md、AI_REVIEW.md
运维交付明确如何上线和排障DEPLOYMENT.md、ENVIRONMENT.md、RUNBOOK.md
AI 协作让 AI 读到稳定规则CLAUDE.md 或 AGENTS.md、PROMPTING.md

最小可用版本 ​

如果项目刚启动，不需要一次写满所有文件。最小集合建议：

  1. README.md
  2. docs/product/PRD.md
  3. docs/architecture/OVERVIEW.md
  4. docs/api/API_SPEC.md
  5. docs/development/SETUP.md
  6. docs/development/CODING_STANDARDS.md
  7. docs/testing/TEST_STRATEGY.md
  8. docs/operations/DEPLOYMENT.md
  9. Claude 项目加 CLAUDE.md，Codex 项目加 AGENTS.md

维护原则 ​

  • 每个文件只回答一类问题，避免变成杂货铺。
  • 重要决策写入 docs/architecture/ADR/，不要埋在聊天记录里。
  • API、环境变量、部署流程变化后同步更新文档。
  • AI 协作文件要短、准、可执行，优先写命令、路径、边界和完成标准。