第一次把 AI 编码工具接入真实仓库：从 git status 到安全改代码的实战流程

第一次把 Claude Code、Codex CLI、Cursor agent 或其他 AI coding agent 放进真实仓库时，最容易犯的错不是“模型选错”，而是太快进入了“帮我改代码”。

真实仓库和 demo 不一样。
真实仓库里有未提交改动、历史约定、脚本依赖、构建失败、Windows 环境差异、部署流程和别人正在做的工作。

所以第一次接入时，目标不是让 agent 显得很聪明，而是让它先变得可控、可验证、可回退。

先给结论

第一次让 AI coding agent 进入真实仓库，我建议按这个顺序：

1. 看清 git 状态
2. 找到仓库入口
3. 识别技术栈和验证命令
4. 限定任务范围
5. 先做最小补丁
6. 跑验证
7. 把经验写回仓库

这比一上来让 agent “全面优化项目”稳得多。

第 0 步：先告诉 agent 当前 shell

如果你在 Windows 上工作，第一句话就应该告诉 agent：

当前环境是 Windows PowerShell，不要默认使用 bash 语法。
需要运行命令时，优先写 PowerShell 可执行的命令。

很多小事故都来自 shell 误判。
比如在一些 PowerShell 版本里，下面这种写法可能不能用：

npm test && npm run build

更稳的是拆开执行：

npm test
npm run build

或者用 PowerShell 的显式判断：

npm test
if ($LASTEXITCODE -eq 0) {
  npm run build
}

如果 agent 不知道当前 shell，很容易把 Linux / macOS 的命令习惯带进 Windows 项目。

第 1 步：先看 git 状态，不要直接改

真实仓库第一条命令应该是：

git status --short

如果你想看当前分支：

git branch --show-current

如果已经有改动，继续看差异：

git diff --stat
git diff -- path/to/file

这里最重要的原则是：

不要让 agent 回滚它没创建的改动。

如果工作区不干净，可以这样给 agent 下指令：

当前仓库可能有未提交改动。你只能编辑和本任务直接相关的文件。
不要执行 git reset、git checkout -- 或任何会回滚用户改动的命令。
如果发现已有改动影响任务，先说明再继续。

这条规则看起来啰嗦，但非常值钱。
很多 AI 改仓库的事故，都不是代码不会写，而是没有保护已有工作。

第 2 步：让 agent 先找入口，而不是全仓库乱扫

我通常会让 agent 先读这几类文件：

Get-Content README.md -TotalCount 200
Get-Content package.json -TotalCount 200
rg --files

如果仓库有 handoff 或开发规则，也要先读：

rg --files | rg "HANDOFF|AGENTS|CLAUDE|README|CONTRIBUTING"

找到以后再读对应文件：

Get-Content docs\TASK_HANDOFF.md -TotalCount 240
Get-Content AGENTS.md -TotalCount 240

不要一开始就要求：

把整个项目完整分析一遍。

这会消耗很多上下文，也容易让 agent 被无关文件带偏。

更好的说法是：

先只读 README、package.json、handoff 和与本任务相关的文件。
读完后告诉我：项目怎么启动、默认验证命令是什么、本任务可能涉及哪些文件。

第 3 步：确认技术栈和验证命令

Node 项目可以先看 package.json：

Get-Content package.json -TotalCount 240

重点看 scripts：

{
  "scripts": {
    "dev": "astro dev",
    "build": "astro build",
    "test": "vitest",
    "validate:content": "node scripts/validate-content-frontmatter.mjs"
  }
}

然后让 agent 明确：

• 改内容，跑什么
• 改前端，跑什么
• 改 API，跑什么
• 改测试，跑什么

一个可复制的指令是：

请先从 package.json 推断本仓库的验证命令。
如果只是改文章内容，优先运行内容校验和 build。
如果改组件或业务逻辑，补跑相关测试。
不要在没确认脚本含义前随便新增依赖。

如果项目没有清晰验证命令，第一次接入就更要保守。

第 4 步：限定改动范围

不要给 agent 这种任务：

帮我优化这个项目。

真实仓库里，这句话太宽了。

更好的任务写法是：

只修改 src/content/posts 下这两篇文章。
不要改 layout、导航、构建配置、package-lock 或部署脚本。
完成后运行 npm run validate:content 和 npm run build。

或者：

只修复 src/components/LoginForm.tsx 里的表单校验问题。
不要调整样式系统，不要改 API 路由。
完成后跑 npm test -- LoginForm。

给 agent 的边界越清楚，它越容易交付一个可 review 的补丁。

第 5 步：先做最小补丁

第一次接入真实仓库时，不要追求一次解决所有问题。
先让 agent 做一个小补丁，观察它是否遵守边界。

比如：

先只完成第一处修复，不要顺手重构。
改完后停下来说明你改了哪些文件、为什么改、准备怎么验证。

如果这个小补丁质量稳定，再继续扩大范围。

这个节奏对个人开发者尤其重要。
因为你不是在测试 agent “能不能写代码”，你是在测试它能不能进入你的工程节奏。

第 6 步：验证不要只靠“看起来没问题”

改完后，至少要跑一轮和任务匹配的验证。

内容站常见命令：

npm run validate:content
npm run build

普通前端项目常见命令：

npm test
npm run build

如果要看端口是否被占用：

Get-NetTCPConnection -LocalPort 4321 -ErrorAction SilentlyContinue

如果要检查某个文本是否还存在：

rg "FIXME|console.log|debugger" src

如果要确认没有误改太多文件：

git status --short
git diff --stat

验证不是仪式感。
它是让 agent 的改动能进入真实项目的最低门槛。

常见问题 1：build 原本就失败怎么办

先不要急着让 agent 修所有错误。
应该先判断失败是否和当前任务有关。

可以让 agent 这样做：

build 失败后，先判断错误是否由本次改动引起。
如果错误来自本次改动，修复它。
如果错误是已有问题，只记录错误摘要，不要扩大修改范围。

常用排查命令：

git diff --stat
npm run build

如果错误指向你没碰过的模块，要谨慎。
真实项目里经常会有“原本就挂”的测试或构建警告，不要让 agent 借机开一轮大修。

常见问题 2：依赖没装怎么办

先看项目使用哪个包管理器。

Get-ChildItem package-lock.json, pnpm-lock.yaml, yarn.lock -ErrorAction SilentlyContinue

如果是 package-lock.json，优先：

npm ci

如果只是本地缺依赖，不要让 agent 直接切换包管理器，也不要随便删除 lockfile。

给 agent 的指令可以是：

如果依赖缺失，先根据现有 lockfile 选择安装命令。
不要切换 npm / pnpm / yarn。
不要删除 lockfile。

常见问题 3：PowerShell 命令不兼容怎么办

最常见的坑包括：

• && 在某些 PowerShell 环境不可用
• 环境变量写法不同
• 路径分隔符不同
• 引号转义不同

PowerShell 设置环境变量：

$env:NODE_ENV = "production"
npm run build

Bash 写法不要直接照搬：

NODE_ENV=production npm run build

如果 agent 连续写出 bash 命令，你可以直接纠正：

请改写为 Windows PowerShell 命令，不要使用 bash 环境变量语法和 Linux-only 命令。

常见问题 4：agent 想顺手重构怎么办

第一次接入时，最怕“修一个 bug，顺手重构五个模块”。

你可以给一个硬边界：

本次任务只允许最小必要改动。
不要改命名、不要抽新框架、不要移动文件。
如果你认为需要重构，先写成建议，不要直接实施。

这不是不信任 agent。
这是为了让每次改动都能被 review。

常见问题 5：改完后不知道怎么交接怎么办

让 agent 用固定格式收尾：

请按下面格式汇报：
1. 改了哪些文件
2. 每个文件为什么改
3. 跑了哪些验证命令
4. 还有哪些风险或没验证的地方
5. 下一步建议

这个格式非常适合真实仓库协作。
因为它让 review 人不用重新猜一遍 agent 的思路。

一条可以直接复制给 agent 的首次接入指令

你现在要接入一个真实代码仓库。请先不要改代码。

当前环境是 Windows PowerShell。

第一步只做仓库理解：
1. 运行 git status --short，确认工作区状态。
2. 阅读 README.md、package.json，以及仓库里的 handoff / AGENTS / CLAUDE / CONTRIBUTING 类文件。
3. 用 rg --files 找到和本任务相关的文件。
4. 总结项目技术栈、默认验证命令、可能涉及的文件。

规则：
- 不要回滚用户已有改动。
- 不要执行 git reset、git checkout -- 或删除文件。
- 不要新增依赖，除非先说明原因并得到确认。
- 不要做无关重构。
- 后续改动必须保持最小范围，并在完成后运行相关验证命令。

如果你只记一段，就记这段。

第一次成功后，要写回仓库

一次成功的 AI 接入，不应该只停留在聊天记录里。
最有价值的是把经验写回仓库，比如：

• AGENTS.md
• docs/START_HERE.md
• docs/TASK_HANDOFF.md
• docs/COMMON_ERRORS.md

最小内容可以是：

# Agent Entry

## Start Here

- Read `README.md`
- Read `package.json`
- Read `docs/TASK_HANDOFF.md` if present

## Default Verification

- Content changes: `npm run validate:content && npm run build`
- Frontend changes: `npm test && npm run build`

## Hard Rules

- Do not revert user changes.
- Do not change deployment config without explicit request.
- Keep edits scoped to the task.

这样下一次 agent 进来，就不需要重新摸黑。

继续阅读

• 怎样让 AI coding agent 更容易读懂你的仓库
• AI 编码工具到底更适合放在 IDE 里，还是终端里？
• Claude Code vs Codex CLI
• Claude Code 安装教程
• Windows 上搭 AI 编程环境，有哪些值得长期看的实战资源？