vibe‑coding 九阳神功之抄：使用优秀项目搭建基础架构

拐爷2026-01-31 16:03

AI 编程现在最大的坑不是"不会写"，而是：

  • • 写得太快

  • • 改得太多

  • • 炸了没后路

  • • 炸完你甚至不知道它到底改了哪些文件

所以我准备写一套 vibe‑coding 九阳神功：核心不是提示词，而是把 AI 变成"可控交付的队友"。

这套"九阳神功"我先定了九个字诀：

  • • 夯：Git 生存技能（刹车 / 保险 / 录像）

  • • 抄 ：拆解 yfge/orion、ai-shifu/ai-shifu 的优秀骨架，搭底盘

  • • 学：会组合技术栈、会裁决，不懂原理也能不翻车

  • • 喂：把 API 文档 / 资料结构化成可执行知识

  • • 规 ：让 AI 出计划 + tasks.md，按清单推进

  • • 验：多模型交叉验证，专治幻觉

  • • 测：Chrome MCP 自动测试，交付有证据

  • • 扩：扩展认知边界，但必须可验证

  • • 收：上线交付、监控回滚、复盘闭环

一句话：不是教你"让 AI 写代码"，是教你"带着 AI 把东西交付上线"。

这篇咱们讲第二式 抄：不做架构分析，先把东西跑起来，再把可复用的"底盘"抽出来。

这节很粗暴：先跑起来，再把底盘抄出来

你可以让 Codex / Claude 帮你敲命令、生成文件、写脚本------但你必须知道它在做什么：git clone 会拉代码；docker compose 会起哪些服务；docker compose down -v 可能会删数据。

你需要准备的就两样：

  • • Git（至少保证 git --version 能跑）

  • • Docker Desktop（自带 Docker Engine + Docker Compose）

0）为什么我推荐这两个项目当蓝本？

Orion：小而全、vibe-coding 味很正

它在仓库里把"documentation-first、agent-friendly、可审计（agents_chat）"写得很明确，而且是把规矩写进工程约束里的那种（不是口号）：

  • • 单一真源的 Agent 规矩 ：AGENTS.md 是 source of truth；.cursorrules / .CLAUDE.md / GEMINI.md（以及 GitHub instructions）都要求链接到同一个文件，避免"多份规则互相打架"。

  • • 强可审计协作 ：agents_chat/ 有严格的命名/模板；并且对"哪些目录算代码变更、必须同提交带 agents_chat"有明确说明，甚至有 CI 检查脚本来强制执行。

  • • 根目录可跑 ：根目录 docker-compose.yml + Docker/（backend/frontend Dockerfile、nginx.conf）直接一条命令能把 MySQL + FastAPI + Next.js + Nginx 拉起来（对照 docker-compose.yml 你能一眼验收它起了哪些服务）。

Orion README

AI-Shifu：大而稳、Docker 自托管做得很成熟

它的亮点更偏"自托管工程化落地"，尤其适合你抄一个可交付的 Docker 底盘：

  • • docker/ 目录集中化 ：启动相关都在 docker/（Nginx 配置、数据卷目录、compose 文件等），读者不容易迷路。

  • • Compose 三件套 ：docker-compose.latest.yml（追最新镜像）+ docker-compose.yml（pin 版本可复现）+ docker-compose.dev.yml（源码挂载/热更新）。

  • • dev_in_docker.sh：一键 build 本地源码镜像，然后起 dev compose（bind mount + reload），非常适合"我不想在本机装一堆 Python/Node 环境"的人。

  • • Nginx 反代更细 ：比如把 /api/i18n、/api/config 这类"前端自己的 API"明确反代到 Cook Web，而 /api/ 才走后端，边界很清晰。

AI-Shifu README

你这一节要"抄"的就是两家的并集优点：

  • • （Orion）工程纪律 + 可审计协作

  • • （AI-Shifu）docker/ 目录化 + .env 模板 + Docker Compose 双轨 + dev 脚本

PS: 别忘了顺手给这两个项目加个star/fork 吖 ：）

1）补齐：git clone 是什么、怎么用（小白够用版）

git clone 的意思很直白：把 GitHub（或其他平台）上的远程仓库，完整复制一份到你的电脑上。

你执行完 git clone ... 后，会得到一个本地文件夹（通常叫仓库名），里面就是项目源码；后面所有 docker compose ... 之类的命令，都是在这个文件夹里运行。

如果你连 Git 都还没安装/没配过，先把"能跑 git --version"这一步搞定再回来看这里（完整入门我单独写在 夯：Git 刹车系统 那篇里）。

go 复制代码 
# 1) 直接克隆到当前目录
git clone <仓库地址>

# 2) 克隆并指定本地目录名
git clone <仓库地址> <本地目录名>

# 3) 克隆后进入目录
cd <目录名>

新手建议先用 HTTPS（省事）。SSH 你第一课配过也可以用。

2）把两个项目 clone 下来（照抄命令就行）

建议先建个练功目录：

go 复制代码 
mkdir -p ~/dev/vibe-practice
cd ~/dev/vibe-practice

# clone Orion
git clone https://github.com/yfge/orion.git

# clone AI-Shifu
git clone https://github.com/ai-shifu/ai-shifu.git

如果你跟我一样，本机已经把两个项目放在固定位置，也可以直接用你现成的路径（本文后续示例按这个来写）：

  • • Orion：~/dev/vibe-practice/orion

  • • AI-Shifu：~/dev/vibe-practice/ai-shifu

3）装 Docker（Windows / macOS 小白版）

你后面"一键启动"全靠 Docker Desktop（自带 Docker Compose）。

Windows（Docker Desktop + WSL2）

  • • 按官方步骤安装 Docker Desktop for Windows

  • • 建议使用 WSL2 后端（官方也有配置说明）

  • • 装完验证：

go 复制代码 
docker --version
docker compose version
docker run --rm hello-world

（也可以参考微软的 WSL2 + Docker Desktop 指引）

macOS（Docker Desktop）

  • • 按官方步骤安装 Docker Desktop for Mac

  • • 装完验证：

go 复制代码 
docker --version
docker compose version
docker run --rm hello-world

备注：Docker Desktop 的商业使用条款/订阅要求，官方文档有写（别踩坑）。

4）先跑起来：一键启动这两个项目（你只要复制粘贴）

4.1 启动 AI-Shifu（官方 Quick Start，最适合小白）

go 复制代码 
cd ~/dev/vibe-practice/ai-shifu/docker
cp .env.example.full .env

# 编辑 .env：至少填一个 LLM API Key（例如 OPENAI_API_KEY=...）
docker compose -f docker-compose.latest.yml up -d
docker compose ps

它的 README 基本就是这么写的（含 latest vs pinned 的解释、dev_in_docker.sh 等）。

第一次启动会拉镜像，可能要等一会儿；docker compose ps 能看到服务起来了没。

4.2 启动 Orion（直接用它的 docker-compose.yml）

go 复制代码 
cd ~/dev/vibe-practice/orion
docker compose up -d
docker compose ps

Orion 仓库根目录直接有 docker-compose.yml，也有 tasks.md / agents_chat/ /（链接到 AGENTS.md 的）.cursorrules / .CLAUDE.md / GEMINI.md 这一套 vibe-coding 规矩。

注意：我这份 orion 的 compose 里，Nginx 对外端口是 8082（ports: "8082:80"），所以你应该访问 http://localhost:8082；不要想当然以为都是 8080。
小白提醒：别乱用 docker compose down -v。-v 可能会把 volume 数据也删掉。你不知道它会删什么，就先别用。

5）让 AI "直接抄并集优点"给你生成一个初始系统（不分析骨架，直接开干）

你现在要做的事只有一句话：

在你本地已经 clone 的两个项目基础上，参考 Orion + AI-Shifu 的"规矩文件 + Docker 启动方式"，生成一个全新的可交付项目底盘。

建议你把"参考源"的本地路径也明确告诉 AI（避免它瞎猜）：

  • • Orion：~/dev/vibe-practice/orion（重点看 AGENTS.md 的"单一真源 + 链接策略"、agents_chat/ 的可审计约束、根目录 docker-compose.yml + Docker/）

  • • AI-Shifu：~/dev/vibe-practice/ai-shifu（重点看 docker/ 目录：latest/pinned/dev 三套 compose、dev_in_docker.sh、nginx.conf/nginx.dev.conf）

5.1 你要生成的新项目约束（并集 + 取优）

项目名：vibe-starter

必须包含这些"并集约束"（照抄）：

  • • 工程纪律（Orion 风格）

    • • documentation-first：README / docs/ 先行

    • • agent-friendly：给 AI 的规则文件放根目录

    • • auditable：保留 agents_chat/（记录 AI 协作日志），并提供一套"写法 + 强制机制"

    • • pre-commit：提供可直接使用的 .pre-commit-config.yaml，并在 README 写清楚 pre-commit install / pre-commit run -a 的最小用法（让格式化与基础静态检查自动化）

  • • Docker 化（AI-Shifu 风格）

    • • docker/ 目录集中管理一切

    • • .env.example.full（或等价）+ .env 运行

    • • docker-compose.latest.yml（追最新）+ docker-compose.yml（固定版本可复现）

    • • dev_in_docker.sh：本地源码构建并启动 dev compose（热更新/挂载）

    • • 一键启动脚本：./scripts/up.sh（或 make up）

  • • 基础技术栈（简单但可交付）

    • • backend：FastAPI（至少 /healthz、/api/hello）

    • • frontend：Next.js（首页显示 "it works"）

    • • nginx：/api -> backend，/ -> frontend

    • • MySQL：默认随 docker compose 启动，backend 用 env 连接

    • • 端口统一：对外只暴露 8080

5.2 直接给 Codex / Claude 的指令（复制粘贴就能用）

把下面这段原样丢给你的 Codex / Claude（很关键：要求它按文件创建，别一坨糊你一屏）：

go 复制代码 
你现在要在当前目录创建一个新仓库 vibe-starter。

参考源（已在本地）：
- Orion: ~/dev/vibe-practice/orion
- AI-Shifu: ~/dev/vibe-practice/ai-shifu

目标：同时参考两者的工程习惯与 Docker 启动方式，取并集优点，产出一个"可交付的最小底盘"。

约束（必须满足）：
1) 根目录规则文件齐全：.cursorrules / AGENTS.md / CLAUDE.md(or .CLAUDE.md) / GEMINI.md / tasks.md / README.md
2) 创建目录：agents_chat/、docs/、scripts/、backend/、frontend/、docker/
3) docker/ 目录必须提供：
   - .env.example.full（或等价）+ .env 运行
   - docker-compose.latest.yml（追最新）+ docker-compose.yml（固定版本可复现）+ docker-compose.dev.yml（热更新/挂载）
   - nginx.conf
   - backend/frontend 的 Dockerfile
   - dev_in_docker.sh（开发态：本地源码挂载 + 热更新）
4) scripts/ 目录必须提供：
   - up.sh：一键启动（默认 latest compose）
   - down.sh：停止（不要带 -v）
5) 基础技术栈：
   - backend: FastAPI（至少 /healthz、/api/hello）
   - frontend: Next.js（首页显示 "it works"，并调用 /api/hello 展示返回）
   - nginx: /api -> backend，/ -> frontend
   - MySQL: 默认随 docker compose 启动，backend 用 env 连接
   - 端口统一：对外只暴露 8080
6) 启动即自愈（自动迁移）：
   - `docker compose up` 后端容器启动时必须**自动执行数据库迁移**（例如 Alembic `upgrade head`），并且要**等待 MySQL 就绪**再迁移，迁移成功后再启动服务；避免要求用户手动执行迁移命令。
7) pre-commit 规则（开箱即用）：
   - 仓库根目录必须提供 `.pre-commit-config.yaml`
   - README 必须写清楚：`pre-commit install`（含 commit-msg 如有）与 `pre-commit run -a`
   - 规则目标：自动格式化 + 基础静态检查（至少覆盖 backend Python；frontend 可选接入 prettier/eslint）
8) agents_chat 机制（可审计协作，开箱即用）：
   - 目录：`agents_chat/YYYY/MM/DD/`
   - 文件名：`YYYY-MM-DDTHH-MM-SSZ-<topic>.md`
   - 每条日志必须包含 YAML frontmatter（至少：`id/date/participants/models/tags/related_paths/summary`）
   - 正文必须包含：需求/背景、做了什么（含改动文件）、关键决策、验收结果、后续 TODO
   - 强制规则：凡提交涉及代码/配置变更（例如 `backend/`、`frontend/`、`docker/`、`docker-compose*.yml`），同一次提交必须新增/更新至少一条 `agents_chat/` 日志
   - 例外：允许在提交信息中加入 `skip agents-chat` 跳过（强调"有意为之、少用"）
   - 实现方式：提供一个可运行的检查脚本（CI 或 pre-commit 阶段均可）来 enforce 上述规则

补一句：上面这段"提示词/约束"是我现在直接给你的 可用模板 ；但你完全可以反过来做------先让 Codex / Claude 分析你本地的两个参考仓库 （例如 ~/dev/vibe-practice/orion 与 ~/dev/vibe-practice/ai-shifu），让它先输出一份"并集优点/目录骨架/关键规矩文件清单/Compose 双轨与 dev 脚本要点"的总结，再让它 基于这份总结生成最终提示词与文件清单。这样更贴合你手上版本，也更可审计（你能对照它的总结逐条验收）。

6）让 AI 给你"一键启动命令"，你只负责验收

你让 AI 最后输出这两类命令即可：

一键启动（latest）

go 复制代码 
cd vibe-starter
cp docker/.env.example.full docker/.env

# 编辑 docker/.env：至少填一个 LLM key（如果你项目需要的话；本 starter 可不填）
./scripts/up.sh

验收（必须给证据）

go 复制代码 
docker compose -f docker/docker-compose.latest.yml ps
curl -s http://localhost:8080/api/hello

# 浏览器打开 http://localhost:8080

核心心法：命令让 AI 写，验收你自己做。

你不需要懂 Dockerfile 细节，但你必须看得懂"它启动了哪些服务、暴露了什么端口、接口是否通"。

7）这一节结束的"交付物"（你要拿到什么才算学会）

你最终应该得到一个新仓库 vibe-starter，满足：

  • • docker compose up -d 能跑起来（对外 8080）

  • • 根目录规则文件齐全（给 AI 的约束一次写清）

  • • 有 tasks.md（按清单推进，可复现）

  • • 有 agents_chat/（记录协作过程，可审计）

  • • 有一键脚本（up/down/dev）

做到这一步，你就已经有了 vibe-coding 的"底盘"：这时候你就可以更自由地往项目里加功能了------因为你"抄"来的强规范（可审计、可回滚、可验收）会把你牢牢拉在轨道上，不容易跑偏。比如你想加"用户注册/登录"就放心加；当然你也可以继续"抄"，比如参考 AI-Shifu 的做法，把大模型调用这一套干净地接进来。

热门推荐
01GitHub 镜像站点02Clawdbot 中文汉化版 接入微信、飞书03OpenCode 入门教程：介绍 · 安装 · 配置第三方 API (如 Claude)042026数学建模美赛题目特点与选题建议，常用四大模型汇总05一种新的LCA算法06Claude Code Skills 实用使用手册07零门槛部署本地 AI 助手：Clawdbot/Meltbot 部署深度保姆级教程08在Trae中使用Pencil MCP09UV安装并设置国内源10Linux下V2Ray安装配置指南