教学资源今天

给 AI 编码助手准备一份「开工包」：让开发更稳

> 📌 **阅读提示**： > 本文用一个「个人网站改版」作为贯穿示例，文中统一用 **「你的网站」** 和 **「你的项目目录」** 代指你的真实项目。这

给 AI 编码助手准备一份「开工包」：让开发更稳

📌 阅读提示：
本文用一个「个人网站改版」作为贯穿示例，文中统一用 「你的网站」 和 「你的项目目录」 代指你的真实项目。这些只是占位示例，请替换成你自己的项目——不必纠结示例里的具体业务，重点是学会"开工包"这套方法。

当你用 AI 编码助手（Codex、Claude、Cursor、WorkBuddy 等）做真实项目开发时，每次开新对话都要重新交代背景、反复确认"哪些能动、怎么验证、怎么部署"——既费 token 又容易跑偏。
解决办法：在项目里提前准备好一份开工包，让 AI 第一步就能自己读懂项目、按规矩行事。

一、开工包是什么

开发包本体：

复制粘贴给市面上大多数 AI 编码助手（Codex / Claude / Cursor / WorkBuddy 等）都看得懂、能照做。

通过网盘分享的文件：4.vibe-coding-kickoff-kit.zip

链接: https://pan.baidu.com/s/1LqYYVK14_BKuloGg1sIpJg
提取码: 2r5p

--来自百度网盘超级会员v8的分享

包含内容：

价值说明：

1、节省 token

避免 agent 每次都重新询问项目路径、开发范围、验证方式、部署流程，减少重复沟通和环境侦察。

2、提高开发效率

先建立 git、项目说明文件和固定检查命令，让 agent 不用临时拼命令、不用反复猜项目结构，可以更快进入有效开发。

3、帮助新手少走弯路

新手不懂正规开发流程时，这个 skill 会引导 agent 先做项目初始化、版本记录、本地验证和上线前备份，避免一上来就乱改代码或直接动线上项目。

4、建立更高效的人机协同

让人负责目标、审美和业务判断，让 AI 负责目录检查、流程搭建、代码实现和验证，双方分工更清楚。

5、降低 Windows 环境踩坑概率

提前处理中文 Windows 常见的命令、路径、UTF-8/GBK 编码问题，减少因为工具环境导致的无效报错。

6、让开发流程更正规但不复杂

用轻量方式建立“本地开发 → 本地验证 → 打包更新 → 服务器备份 → 上传部署 → 线上检查”的流程，不要求新手先学完整工程体系。

7、降低线上出错风险

明确“不直接改旧项目、不直接上线未经确认的版本、服务器更新前先备份”，让新手也能更安全地做网站迭代。

开工包不是某个工具，而是你交给 AI 的一整套"项目上下文 + 操作约定"，核心 6 件事：

示意图①：开工包 6 要素总览。git 仓库与项目说明文件是优先级最高的两项，收益最大。

其中 git 库 + 项目说明文件 收益最大，优先做；其余可后续补齐。

git是什么，你只需要知道开发工作需要git，如果你电脑里没有git，agent会帮你下载

它在电脑里长这样：

我自己用的安装包，安装的时候默认下一步就行（开发包本体不包含）：

二、6 件事逐条讲（开工包里的内容）

1. 把新项目变成 git 库（★ 最高优先级）

即便不上传 GitHub，只在本地用 git 也极有价值：

作用	说明
知道改了哪些	`git status` / `git diff` 一眼看清
不误动已有改动	AI 不会在不知情下覆盖你的成果
阶段可存版	每完成一个阶段 `git commit` 一次
出问题能比对	不用靠记忆回忆"昨天长啥样"
打包前确认差异	`git diff` 看"这次到底改了哪些"

最理想流程：

cd D:\你的项目目录
git init
git add -A && git commit -m "init: 初始版本"
# 每完成一个阶段再提交
git commit -m "feat: 核心页面"
git commit -m "feat: 子页面"
git commit -m "fix: 后台入口"

示意图②：Git 工作流。每完成一个阶段（如首页原型、子页结构）就提交一次；出问题时可精确回滚到任意提交点。

2. 根目录放一个给 AI 看的说明文件（★ 最高优先级）

文件名建议：CODE_项目说明.md。AI 第一步读它，就不再反复问项目背景。

模板（直接复制改，把示例内容换成你的项目）：

# CODE_项目说明
# 以下为示例内容，把「你的网站 / 你的项目目录」替换成你自己的

项目名称：你的网站（本次改版项目）
项目根目录：D:\你的项目目录
旧项目参考目录：D:\旧项目\extracted

## 本阶段目标
只开发 PC 端核心栏目，不动旧线上项目。

## 本地启动方式
（在此填写你的启动命令，例如 flask run / python app.py）

## 本地验证方式
- python -m py_compile extracted/app.py
- Flask test client 检查主要路由返回 200

## 部署方式
本地确认 → 打包 extracted 相对路径 → 上传服务器 → 备份旧文件 → 解压覆盖 → 重启服务 → 线上验证

## 不能做
- 不直接上线未经确认的视觉方案
- 不改动与本次无关的其他栏目 / 旧官网
- 不做本次范围外的功能（如移动端）
- 不改动已有的旧功能模块（按你的实际项目列出）
- 不保留已废弃的后台管理入口

这个文件价值最大：它把"项目是什么、能动什么、怎么验证、怎么部署、红线在哪"一次性说清。

3. 准备固定的本地命令

Windows 卡住通常不是 Windows 本身的问题，而是项目没有固定命令，AI 只能每次临时拼。准备几个脚本，以后直接调用：

脚本	用途
`scripts/dev.ps1`	启动本地服务
`scripts/check.ps1`	检查语法 + 路由
`scripts/package.ps1`	打包更新内容

这样 AI 不用每次临时判断"该怎么跑"。示例骨架（按需改写）：

# scripts/check.ps1
python -m py_compile extracted/app.py
python -c "from extracted.app import app; client=app.test_client()
assert client.get('/').status_code==200"

4. 建立清晰目录结构

一开始就贴近旧站结构，让 docs / scripts / packages 各司其职：

示意图③：推荐目录结构。新项目一开始保持接近旧站结构（extracted / templates / static），规划与记录放 docs、脚本放 scripts、更新包放 packages。

D:\你的项目目录
├─ extracted/      # 网站代码（app.py / templates / static）
├─ docs/           # 规划与记录
├─ scripts/        # dev / check / package 脚本
└─ packages/       # 生成的更新包 .tar.gz

这部分不用你自己创建，skill里有，agent会自己创建。

5. 每次部署前保留版本包和备份

你现有的"打包上传解压"流程可以继续，但规范成带版本号的产物：

packages/你的项目-日期-v1.tar.gz
packages/你的项目-日期-v2.tar.gz

服务器侧也保留回滚点：

backup-日期-before-版本

示意图④：部署闭环。本地确认 → 打包 → 上传 → 备份旧文件 → 解压覆盖 → 重启 → 线上验证；验证失败则回滚到备份。

这样线上出问题，直接回滚，不慌。

6. 每次开新对话给一段固定开场白

把下面这段存成你的"开场模板"，每次新对话先发：

请先读取 D:\你的项目目录\CODE_项目说明.md。
本次只在新项目中开发，不动旧线上项目。
先看 git 状态，再按 docs 里的流程继续。

这会省很多 token——因为不用每次重新讲完整背景。

三、优先级与落地顺序

本教程建议的优先级（也是你最该先做的）：

先给新项目建 git（收益最大）
写 CODE_项目说明.md（收益最大）
写最简单的 scripts/check.ps1
后面再补 dev.ps1 / package.ps1 和目录规范化

一句话：git + 项目说明文件最重要。这两件事做好，AI 会少问无数"这是哪个项目、哪些能动、怎么验证、怎么部署"的问题，开发会稳很多。

第3，4条可以用我给的底稿，让agent把它改成适合你自己电脑配置的路径。

四、可直接复用的 Skill：vibe coding 新手小白开工准备

下面这段文本是自包含、跨平台通用的。复制粘贴给市面上大多数 AI 编码助手（Codex / Claude / Cursor / WorkBuddy 等）都看得懂、能照做。可以根据那你自己的习惯修改，并把它单独存成 vibe-coding-开工准备.md，开新项目前发给 agent，或放进 agent 的 skill 目录。

# vibe coding 新手小白开工准备

> 通用 skill · 复制给任意 AI 编码助手即可执行：Codex / Claude / Cursor / WorkBuddy 等。
> 用途：让 AI 在动手写代码前，先把项目「开工包」准备好，开发更稳、少返工、能回滚。

## 触发场景
当你接到一个真实项目的开发任务，且这是一个新对话 / 新项目时，不要立刻写代码。先按下面 6 步把「开工包」准备好，再动手。

## 执行步骤（按优先级）

### 第 1 步【必须】初始化 git
在项目根目录执行：
    git init
    git add -A && git commit -m "init: 初始版本"
之后每完成一个阶段（如核心页面、子页面）再提交一次。
目的：快速知道改了哪些、阶段可存版、出问题用 git diff / git checkout 精确回退、打包前确认差异。

### 第 2 步【必须】写项目说明文件
在根目录创建 CODE_项目说明.md，至少包含：
- 项目名称
- 项目根目录绝对路径
- 旧项目 / 参考目录路径（如有）
- 本阶段目标（只做什么、不动什么）
- 本地启动方式
- 本地验证方式（如 python -m py_compile、路由 200 检查）
- 部署方式（本地确认 → 打包 → 上传 → 备份 → 覆盖 → 重启 → 验证）
- 不能做（红线清单）
优先级最高：你第一步读它，就不再反复问背景。

### 第 3 步【建议】固定本地命令
写 scripts/check（.ps1 或 .sh）检查语法与主要路由；可扩展 dev（启动）、package（打包）。不每次临时拼命令。

### 第 4 步【建议】清晰目录结构
保持：
    项目根/
    ├─ extracted/   # 网站/应用代码
    ├─ docs/        # 规划与记录
    ├─ scripts/     # 检查/启动/打包脚本
    └─ packages/    # 生成的更新包

### 第 5 步【建议】版本包 + 备份
部署前打包：packages/项目名-日期-v1.tar.gz（包内用相对路径）。服务器先备份旧文件再覆盖：backup-日期-before-版本。线上出问题直接回滚。

### 第 6 步【建议】固定开场白
每次新对话，先让人类发：「请先读取 CODE_项目说明.md；本次只在新项目开发、不动旧线上；先看 git 状态，再按 docs 继续。」省 token、不重讲背景。

## 优先级总览
先做第 1、2 步（收益最大）。第 3–6 步后续逐步补齐。

## 给新手的提醒
- 不直接上线未经确认的视觉方案。
- 每阶段本地跑通、预览确认，再考虑上传。
- 保持单一信息源，改动都进 git。

## 可直接复制的开场白模板
请先读取 项目根/CODE_项目说明.md。本次只在新项目中开发，不动旧线上项目。先看 git 状态，再按 docs 里的流程继续。

五、让本skill可进化

1、在日程使用中，如果发现Agent使用了临时命令，就把这类验收沉淀进 scripts/check.ps1，而不是每次临时拼命令。
2、如果有偏 Linux/macOS 的 shell 脚本，则让Agent补一个 Windows 友好的固定验收脚本。