AI Engineering
AI Coding 项目初始化：从空目录到可协作仓库
用 AI 辅助完成项目初始化，覆盖目录结构、README、规则文件、测试脚本、环境变量、安全检查和上线前验收。
项目初始化不是创建几个文件夹，而是建立协作边界。AI Coding 场景下，初始化阶段要让人和 AI 都知道：项目目标是什么、能改哪些文件、如何运行、如何测试、什么不能提交。
核心原则
初始化的目标是降低后续协作成本。仓库越早具备结构、规则、脚本和上下文，AI 生成的改动越容易被审查和验收。
初始化产物
README.md
package.json / pyproject.toml / go.mod
.gitignore
.env.example
AGENTS.md / CLAUDE.md
index.ts
推荐流程
先让 AI 根据目标生成 2-3 套技术方案，人选择路线。
确定包管理器、运行时、测试工具和部署目标。
生成 README、目录结构和最小可运行代码。
补充 AI 协作规则，说明禁止事项、测试命令、代码风格。
加入
.env.example，不要让真实密钥进入仓库。跑一次构建和测试，再做首个提交。
Prompt 模板
我要初始化一个 [项目类型] 项目。
目标：
- [业务目标]
技术约束：
- 语言/框架：...
- 包管理器：npm / pnpm / poetry / go mod
- 部署目标：Vercel / Docker / Cloudflare / 自托管
请先输出：
1. 推荐目录结构
2. README 草稿
3. .gitignore
4. .env.example
5. 最小可运行代码
6. 测试命令和构建命令
7. AGENTS.md 或 CLAUDE.md 协作规则
限制：
- 不要生成真实密钥
- 不要引入不必要依赖
- 先给方案和文件清单，不要直接写代码README 要写清楚什么
| 模块 | 内容 |
|---|---|
| 项目目标 | 这个项目解决什么问题，不解决什么问题。 |
| 快速开始 | 安装、配置、运行、测试的最短路径。 |
| 环境变量 | 每个变量的用途、是否必填、示例值。 |
| 常用命令 | dev、test、lint、build、deploy。 |
| 目录说明 | 哪些目录放业务代码、测试、脚本、文档。 |
| 协作约定 | 分支、提交、PR、代码审查和发布规则。 |
AI 协作规则
项目级规则文件要短，但必须明确。可以包含这些内容：
## Project Rules
- Before editing, inspect existing patterns.
- Use the existing package manager and scripts.
- Do not commit secrets, tokens, credentials, or real customer data.
- After changing code, run: npm run types:check && npm run build.
- Keep changes minimal and avoid unrelated refactors.
- Preserve public routes unless explicitly asked to move them.这类规则不需要写成长文。越具体，AI 越容易遵守；越抽象，越像口号。
目录结构的取舍
小项目优先扁平。目录过早分层会增加跳转成本。
src/
tests/
docs/中型项目按边界组织，而不是按技术名词堆目录。
src/features/
src/lib/
src/server/
src/ui/团队项目需要更明确的所有权、测试和发布边界。
apps/
packages/
docs/
scripts/初始化验收清单
| 项目 | 标准 |
|---|---|
| 运行 | 新同事或 AI Agent 能按 README 跑起来。 |
| 测试 | 至少有一个 smoke test 或构建检查。 |
| 安全 | .env 被忽略，.env.example 可提交。 |
| 规则 | AI 知道测试命令、禁止事项和代码风格。 |
| 结构 | 目录能支撑 2-3 个月内的真实迭代。 |
| 审查 | 首个提交不包含无关脚手架、废弃 demo、真实密钥。 |
常见错误
一个实用结论
AI Coding 项目初始化最重要的不是“生成了多少代码”，而是让仓库形成稳定的协作协议。先把目标、结构、命令、安全边界和验收标准写清楚，后面的 Agent 才能可靠地执行。
讨论
继续讨论这篇笔记
有问题、补充案例或不同观点，可以通过 GitHub Discussions 继续交流。