用于干净交接的 AI 构建代码库导出检查清单

为什么导出的项目在交接后会失败

大多数导出项目失败有一个简单原因：它们在原始平台内能正常运行，因为默认值、密钥、数据库状态和构建步骤都已经到位。一旦代码离开那个泡泡，下一个开发者就不得不去猜测有哪些假设。

一次干净的交接意味着项目可以被克隆、配置并由没有参与构建的人在一台全新的机器上启动，而不需要长时间的来回沟通。它不要求代码完美，而是要求基础事项明确且可重复。

导出失败通常因为相同的问题反复出现：隐藏的配置、不明确的密钥处理、模糊的本地设置步骤、数据库上的意外情况，以及只在一个环境中才工作的 CI。

这就是为什么 AI 构建的代码库导出检查清单主要关注文档与可重复性，而不是简单地复制文件。如果你在像 Koder.ai 这样的 vibe-coding 平台上构建应用然后导出源代码，下一个团队仍然需要一张地图：该设置什么、运行什么，以及“正常工作”是什么样子。

本检查清单聚焦交接要点：环境变量、密钥、本地开发设置、数据库引导、CI 设置，以及一个实用的“如何运行”的 README。不涉及产品决策、UX 打磨或架构重构。

责任也应该明确。构建方负责把假设显性化（文档、脚本、安全默认值）。接收方负责把项目适配到他们的环境（密钥管理、托管、更严格的 CI 规则）。当双方都清楚自己的职责时，交接就会变成常规操作。

在导出之前：确定交接契约

一次干净的交接始于一个简单的约定：代码离开平台时“完成”意味着什么。没有它，团队之后会为缺失脚本、意外依赖或哪个版本才是真正版本而争论。

选择导出时点

选择一个单一且稳定的时间点，把它当作事实来源。中途导出会导致仓库几乎能运行却不完全运行。

一个合适的导出时点通常为：

• 一个带简短发布说明的稳定提交（说明改了什么、需要测试什么）
• 一个带标签的发布（即使只是 v0.1.0）
• 一个平台快照（例如可以回滚的 Koder.ai 快照，如果需要重复导出时可回滚）

添加一句话说明为什么这是合适的导出时点。例如：“所有核心流程通过，数据库模式对本里程碑已定型。”

决定交接包含哪些内容

写一个简短清单说明接收方应该预期到什么。明确说明哪些包含在内，哪些是有意不包含的。

包含基础项：源代码（应用、服务、共享包）、配置模板（示例 env 文件）、脚本（构建、开发、测试、迁移、填充）、以及部署说明。只有在样本数据已经清洗且安全时才包含样本数据。

然后冻结版本，这样“在我机器上可以运行”就不会成为新的基线。记录运行时和工具链版本（Node、Go、Flutter、包管理器），以及数据库版本（PostgreSQL 的大版本很重要）。

最后列出在运行任何东西之前必须完成的前置事项。保持简短且具体：所需的账号、已安装的工具、必须空闲的端口，以及任何一次性设置步骤。

环境变量：把一切记录清楚，别让东西被藏起来

大多数“在平台上能工作”导出出问题是因为关键配置未被写下来。环境变量是常见罪魁：它们存在仓库外，新团队成员克隆项目后不知道应该设置什么值。

把这当作干净导出的必做项：每个变量都应可被发现、解释清楚并能在不猜测的情况下设置。

在交接 README 中创建一个单一事实来源：列出 env 变量名、它们控制什么、以及值来自哪里。用通俗易懂的语言解释，并标注任何安全相关内容。

每个变量的简单格式：

• Name: 精确键名（可复制粘贴）
• Meaning: 在应用中改变什么
• Required?: 必需或可选（以及缺失时会发生什么）
• Example: 安全的示例值（从不使用真实密钥）
• Where it differs: 开发/预发布/生产 环境间的差异

同时，把一个 .env.example 文件随仓库一起交付。它应包含可能需要的每个变量，并带有安全占位值，以便应用能通过最小修改启动。

# Required
APP_ENV=development
PORT=3000
DATABASE_URL=postgres://user:password@localhost:5432/app_dev

# Optional
LOG_LEVEL=info
CORS_ORIGINS=http://localhost:5173

# Environment specific
PUBLIC_BASE_URL=http://localhost:3000

一些细节能避免大多数混淆：

把“必需与可选”写清楚。如果缺少某个变量会导致崩溃，就说明。如果它启用某个功能（邮件发送、支付、文件存储），请说清楚该功能以及缺失时的表现。

指出每个变量在不同环境下如何变化。DATABASE_URL 和 PUBLIC_BASE_URL 常常在 dev、staging 与 production 间不同，而 LOG_LEVEL 则可能处处相同。如果你使用 Koder.ai 导出并部署，请再次确认平台默认值（端口、基础 URL、允许的来源）已在文档中反映，以便在平台外行为一致。

最后说明本地如何加载 env 变量。如果项目期望一个 .env 文件，说明它位于何处以及应用是自动读取还是需要某个命令/工具来加载。

密钥：别把它们放到仓库里，但要容易设置

密钥是如果泄露会造成损害的值：API key、数据库密码、认证令牌、OAuth 客户端密钥、私钥、Webhook 签名密钥等。

对于导出，保持简单：仓库中只应包含占位符，绝不是真实密钥。如果启动需要某个密钥，在 .env.example 中以明显的占位符名称包含它，并解释如何生成真实值。

一种实用模式是把三件事分开：样本文件、本地文件、以及 CI 或部署的密钥存储。导出的代码应包含样本文件、忽略本地文件，并记录 CI/托管如何接收密钥。

密钥应该放在哪儿

为每个环境选择一种方式并坚持使用。

• 本地开发：.env（被 gitignore）由应用加载，或团队的本地密钥管理方案
• CI：CI 提供商的加密环境变量
• 部署/托管：在托管环境中存储密钥并在运行时注入

示例：仓库里包含 PAYMENTS_API_KEY=replace_me。接收方在服务提供商仪表盘中生成自己的密钥并把它写到本地 .env 与 CI 中。代码保持不变。

增加一次轮换步骤

交接是轮换密钥的好时机，尤其是在它们曾在共享平台会话中使用过时。

• 为外部服务重新签发新密钥并撤销旧密钥。
• 重置数据库密码和任何管理令牌。
• 先更新 CI 与托管中的密钥，然后更新本地 .env 文件。
• 确认应用能启动、测试通过且旧密钥不可用。

如果你是从 Koder.ai 导出的，把导出当做一个新环境并为接收团队生成新的密钥。

本地开发设置：让首次运行变得无聊（可预测）

交接成功的标志是新开发者能克隆仓库、运行几条命令并看到应用工作而无需猜测。目标是可预测的前置条件、清晰的命令顺序和与现实一致的简短“如何运行”块。

前置条件（要明确）

把这些放在 README 顶部，让没人需要从错误信息里去推断：

• 操作系统说明：例如“在 macOS 和 Ubuntu 上测试过”（只有在测试过才添加 Windows 说明）
• 运行时版本：Node.js（用于 React）、Go（用于 API）、PostgreSQL（用于 DB）
• 工具：npm/pnpm/yarn、Make（如果使用）、Docker（仅在依赖时说明）

如果项目是在 Koder.ai 上构建的，本地设置应与导出的内容保持一致（相同的文件夹结构、相同的启动命令）。不要假设“Postgres 已经在跑”，除非你明确说明。

安装与开发命令（每行一条）

把新同事应该按顺序运行的精确命令放在这里，保持可复制粘贴：

# 1) Install dependencies
cd web
npm ci

cd ../server
go mod download

# 2) Create your env file
cp .env.example .env

# 3) Start dependencies (if needed)
# e.g., start Postgres locally or via docker compose

# 4) Run the app
cd server
go run ./cmd/api

cd ../web
npm run dev

在其下方添加最小的测试和构建部分：

# Tests
cd server && go test ./...
cd web && npm test

# Build
cd web && npm run build
cd server && go build ./...

排错：首次运行最常见的失败

大多数“运行不了”的问题归结为几类：

1. 版本不匹配（Node/Go）。症状：依赖或编译错误。解决：安装固定版本并重新安装依赖。

2. 缺少 env 值。症状：配置为 undefined、认证失败、500 错误。解决：对照 .env 与 .env.example 填写必需值。

3. 数据库不可达。症状：连接被拒绝、“数据库不存在”。解决：启动 Postgres，验证 host/port/user，并严格按文档运行数据库初始化步骤。

数据库引导：迁移、填充与重置

当项目从平台导出时，数据库通常是第一个在新机器上出问题的地方。目标很简单：队友应该能从“克隆仓库”到“应用带真实数据运行”而无需猜测。

需要记录并保存在仓库的内容

写下针对一个新 PostgreSQL 的最小步骤，并尽可能把命令放在脚本里。你的交接应回答四个问题：

• 我如何创建数据库与角色（名称、权限、密码来源）？
• 我如何从零运行迁移到最新版本？
• 我如何加载能让应用可用于演示的种子数据？
• 我如何在开发中安全地重置数据库？

如果你已有脚本（Makefile 目标、shell 脚本、任务运行器命令），优先使用脚本而不是描述手动步骤。如果没有，现在就添加一小套脚本。

一个稳妥的引导流程

在各环境（本地、CI、staging）保持流程一致。一个好的基线如下：

# 1) Create role + database (example names)
createuser app_user --pwprompt
createdb app_db --owner=app_user

# 2) Apply migrations
# Replace with your repo's migration command
./scripts/migrate up

# 3) Seed minimal demo data
./scripts/seed

对于填充数据，优先选择最小的可用数据而不是生产级别的转储。填充脚本应能多次运行（幂等插入，或明确标注“仅在空数据库上运行”）。

对于重置，要对安全性做出明确说明。重置命令应默认仅针对本地开发。如果提供破坏性脚本，添加护栏（例如要求 CONFIRM_RESET=1，或检查 APP_ENV=development）。并定义“重置”意味着什么：删除并重建、清空表，还是恢复已知快照。

仓库整洁：哪些应放、哪些不应放到源代码中

当仓库看起来像个杂物箱时，交接会出问题。新来者应该能判断什么重要、什么是生成的、在哪儿修改设置。

提交那些能让项目可重复的内容：锁文件、迁移文件、小型配置模板（如 .env.example）以及任何用于引导应用的脚本。

把个人、生成或敏感文件排除在源码外：本地环境文件、编辑器设置、构建产物、日志、缓存，以及任何授予访问权限的文件（API key、数据库密码、服务账号文件）。

一个简单规则：如果修改会影响所有人，就提交。如果随机器或环境变化，就记录并不提交。

如果你写一段“提交 vs 忽略”的短说明，保持简洁：

• 提交：README、锁文件、迁移、填充脚本、.env.example
• 忽略：.env、密钥文件、构建目录、日志、本地缓存

添加一个简短的目录地图，让结构一目了然。例如：“/backend API 服务，/web 前端，/mobile 应用，/db 迁移与填充，/scripts 引导辅助脚本。”

如果你是从 Koder.ai 导出的，把导出当作这次清理的起点：移除生成的杂物，确认忽略规则，并写好目录地图。

CI 设置：让流水线可重现

当 CI 与本地几乎相同时，交接会安静地失败。如果有人能在笔记本上运行项目，CI 应该运行相同的命令并得到相同结果。

决定每次拉取请求时 CI 必须证明的内容。大多数团队只需一小套：

• 代码风格检查/格式化
• 单元测试
• 构建（前端与服务端均能通过编译）

集成测试与部署步骤也可以，但只有在它们可靠且范围明确时才加入。

让 CI 步骤与本地命令保持接近以避免偏差。如果本地是 make test，CI 也应运行 make test。如果没有 Makefile（或等效任务运行器），考虑添加一个并将其作为共享入口点。

把 env 变量和密钥写清楚

CI 常见的破裂原因是依赖隐藏配置。在 README 中添加一个短节列出 CI 期望的确切变量名。将公共配置与密钥分离。

示例名称（按你的栈调整）：APP_ENV、DATABASE_URL、PORT、JWT_SECRET、S3_BUCKET、STRIPE_API_KEY。在 CI 中，密钥应来自 CI 的密钥存储，绝不应提交到仓库。对于常见的 Go + Postgres 后端，还要指出迁移是否自动运行或需要显式步骤。

用状态检查保护合并

决定哪些检查在合并前必需并写下来。“lint + unit tests + build” 通常就够了。如果添加了可选任务（例如移动端构建），除非确实需要，否则把它们设为非阻塞。

还要让 CI 的输出便于排查：打印工具版本并在失败时给出清晰信息。流水线稳定后可以考虑加入缓存。

示例交接场景：从克隆到运行应用

Maya 收到一个从 Koder.ai 导出的项目。典型配置：React 前端、Go API 和 PostgreSQL 数据库。她应该能克隆仓库并在不猜测的情况下看到工作画面。

她的前 30 分钟流程应该像这样：

1. 克隆仓库并打开根目录 README。
2. 将 .env.example 复制为 .env（或在 shell 中设置相同值），分别为 web 与 api 配置。
3. 启动 PostgreSQL（本地或 Docker）并创建空数据库。
4. 运行迁移并填充以获得已知的起始数据集。
5. 启动后端，再启动前端，在浏览器中加载应用。

在混乱的交接中，她通常会遇到三类阻塞问题。

第一：应用启动后崩溃并报出模糊的“缺少配置”错误。真正的问题是未记录的变量，如 AUTH_JWT_SECRET 或要求特定格式的 DATABASE_URL。如果 README 列出每个必需变量、给出安全示例值并说明用途，这就会成为一个快速修复。

第二：API 启动了，但每页显示“无数据”或返回 500 错误。数据库存在但没有表或没有填充数据。干净的交接会提供一到两个可靠命令：运行迁移、填充最小演示数据，并提供重置命令以便出问题时恢复。

第三：一切都在运行，但前端指向了错误端口。Maya 打开了 localhost:3000，但 API 期望 localhost:8080，或 CORS 导致请求被阻止。这时一致的默认配置就很重要：在一个地方设置 WEB_PORT、API_PORT 和 API_BASE_URL，并在 README 中说明本地预期的 URL。

最终检查清单、常见陷阱与下一步

交接只有在别人能从干净克隆运行项目且不需提问时才算完成。证明项目能在平台外存活。

在一台新机器或可丢弃容器上做一次“干净克隆”测试。不要重用已有文件夹、缓存依赖或本地数据库。严格按 README 操作。如果你不得不即兴改动，修正文档或脚本直到不再需要。

能捕捉大多数失败的快速检查：

• README 有一条单一可复制粘贴的“本地运行”路径，外加简短的“如何测试”。
• .env.example 存在，并对每个必需变量提供安全示例值与解释。
• 数据库引导端到端可用：创建 DB、运行迁移、可选填充，以及重置命令。
• CI 能在干净 Runner 上运行并与本地命令一致。
• 新开发者能做一个小改动、运行测试并在应用中看到结果。

常见陷阱往往很平凡，因此常被忽视：

• 未写进文档的一次性步骤
• README 与旧的文件结构或旧命令不一致
• 硬编码值（API URL、功能开关、密钥）写死在代码中而非配置中
• 密钥以非正式方式共享且没有明确安全设置流程
• CI 之所以通过是因为依赖缓存或本地服务

下一步：指定一位负责人在 24 到 48 小时内验证导出，而不是几周后。让他们做干净克隆测试并报告差距。

如果你在 Koder.ai（koder.ai）上构建，把这份清单视为常规工作流的一部分：使用 planning 模式写下运行路径，在重大改动前拍快照，并按计划导出源代码，使交接包保持最新。