06 · 跑通第一个任务：让 Codex 改一次代码

这一篇开始真正上手。

但先说结论：第一次不要拿正式项目练手。

你要先做一个很小的玩具项目，让 Codex 只改一个文件、一个函数。这样它改了哪里，你一眼能看清楚；改错了，也能马上撤回。

这一篇最重要的不是 Python，也不是类型注解，而是学会一个以后天天会用的动作：

看 diff。

也就是看清楚 Codex 到底删了什么、加了什么、有没有碰你没让它碰的地方。

开始前先把任务缩到最小

第一次任务只追求一件事：

让 Codex 改一个很小的文件，然后你看懂它改了什么。

不要做网站。 不要连数据库。 不要部署服务器。 不要让它“顺便优化一下”。

你这次只练 4 个动作：

1. 让它读。
2. 让它改。
3. 看 diff。
4. 验证结果。

先把这 6 步抄在旁边

如果你是第一次用 Codex，不要一边想一边做。 直接按下面 6 步走：

1. 新建一个空文件夹。
2. 放一个最小代码文件。
3. 用 Git 保存初始版本。
4. 让 Codex 先解释，不要修改。
5. 让 Codex 只改一个文件。
6. 看 diff，确认它没有乱改。

这 6 步就是你以后做真实项目的缩小版。 先在玩具项目里练熟，正式项目就不会慌。

这一篇你要完成什么

照着做完，你会跑通一整圈：

1. 建一个很小的练习项目。
2. 写一个只有两行的 Python 文件。
3. 让 Codex 先解释这个文件。
4. 再让 Codex 修改这个函数。
5. 看它给出的 diff。
6. 用 git diff 再确认一次。

如果你不会 Python，也没关系。这里的代码只是练习道具。

第一步：新建一个玩具项目

先打开终端。

Windows 可以用 PowerShell，Mac 可以用 Terminal。

复制下面两行：

mkdir hello-codex
cd hello-codex

这两行的意思很简单：

1. mkdir hello-codex：新建一个叫 hello-codex 的文件夹。
2. cd hello-codex：进入这个文件夹。

为什么要建新文件夹？

因为第一次练习最怕的不是 Codex 不会干活，而是你看不懂它改了什么。正式项目文件太多，第一次就进去改，很容易慌。

这个 hello-codex 就是你的练习场。

第二步：创建一个最小代码文件

现在在 hello-codex 里创建一个 main.py。

如果你熟悉命令行，可以用下面这段：

echo "def add(a, b):" > main.py
echo "    return a + b" >> main.py

如果你不熟悉命令行，就用最笨但最稳的办法：

1. 打开 hello-codex 文件夹。
2. 新建一个文本文件。
3. 文件名改成 main.py。
4. 把下面两行粘进去：

def add(a, b):
    return a + b

这个文件的意思是：定义一个 add 函数，输入两个数，返回它们相加的结果。

你不需要现在学会 Python。你只要知道：这是一个小到不能再小的代码文件，适合第一次让 Codex 练手。

第三步：先给项目打一个存档点

这一步很重要。

我们先用 Git 记录“修改前”的状态。这样 Codex 改完后，你才能清楚看到差异。

复制：

git init
git add main.py
git commit -m "first version"

你可以把 Git 理解成项目存档工具。

这三行的意思是：

1. 开启存档功能。
2. 把 main.py 放进存档。
3. 记录一个叫 first version 的版本。

如果这里报错，说没有配置用户名或邮箱，先不用慌。你可以把报错完整复制给 Codex，让它一步一步带你配置。

第四步：让 Codex 先解释，不要马上修改

现在打开 Codex，让它进入 hello-codex 这个文件夹。

第一句话不要让它改代码，先让它解释：

请解释 main.py 这个文件在做什么，用新手能听懂的话说。暂时不要修改任何文件。

你要看它有没有说出类似意思：

这个文件里有一个 add 函数，它接收 a 和 b 两个参数，然后返回 a + b 的结果。

这一步的目的不是学 Python。

这一步的目的是确认：Codex 真的读到了你的真实文件，而不是在凭空猜。

第五步：让 Codex 做第一次小修改

确认它读懂文件以后，再发这句：

请给 main.py 里的 add 函数加上类型注解，并补充一个基础检查：如果传入的不是数字，就抛出 TypeError。

要求：
1. 只修改 main.py
2. 修改后先展示 diff
3. 用新手能听懂的话解释你改了什么

这句话里有三个关键限制：

1. 只修改 main.py。
2. 要展示 diff。
3. 要解释改动。

新手最怕的是它一口气改很多文件，所以这里必须把范围锁死。

第六步：看懂 diff

Codex 改完后，你要重点看 diff。

diff 可以理解成“修改前后对比”。

你只要先记住两种符号：

- 代表删除的旧内容
+ 代表新增的新内容

这次你大概会看到类似变化：

- def add(a, b):
-     return a + b
+ def add(a: float, b: float) -> float:
+     if not isinstance(a, (int, float)) or not isinstance(b, (int, float)):
+         raise TypeError("a 和 b 必须是数字")
+     return a + b

你不用看懂每个技术细节，但要检查三件事：

1. 它是不是只改了 main.py？
2. 它是不是还保留了“两个数相加”的功能？
3. 它有没有多改其它文件？

如果你看不懂，就直接问：

请用普通人能听懂的话解释这个 diff。重点告诉我：删了什么、加了什么、有没有改到 main.py 以外的文件。

第七步：回到终端再确认一次

现在回到终端，在 hello-codex 文件夹里执行：

git diff

你应该能看到和 Codex 展示类似的改动。

如果你只是想看文件内容，可以用：

type main.py

Mac 可以用：

cat main.py

你要确认两件事：

1. main.py 真的被改了。
2. 改动和你刚才看到的 diff 对得上。

这一步很关键。它会让你知道：你看到的 diff，不是讲故事，而是真实落到文件里的变化。

第八步：如果改错了怎么办

如果你发现 Codex 改错了，先不要慌。

你可以先让它自己修：

这次修改不符合我的预期。请先不要继续扩大修改范围，只在 main.py 里把问题修正，并再次展示 diff。

如果你想直接回到修改前，可以用 Git 撤回：

git restore main.py

这条命令的意思是：把 main.py 恢复到上一次存档时的样子。

注意：第一次练习时，只在这个玩具项目里用。不要在正式项目里随便执行你不理解的恢复命令。

桌面 App 怎么做

如果你用的是 Codex 桌面 App，流程一样，只是不用一直敲命令。

你按这个顺序走：

1. 打开 Codex App。
2. 选择 hello-codex 文件夹。
3. 先发“解释 main.py”的提示词。
4. 确认它读懂后，再发“修改 add 函数”的提示词。
5. 在界面里查看它展示的改动。
6. 如果看不懂，就让它解释 diff。

桌面 App 的好处是看改动更直观。

但核心还是同一个：Codex 改完，你要审 diff。

这一篇真正练的是什么

表面上看，我们只是改了一个小函数。

实际上，你练的是 Codex 的最小闭环：

1. 建一个安全练习项目。
2. 让 Codex 先读不改。
3. 再让 Codex 做一个小修改。
4. 看 diff。
5. 验收结果。
6. 不满意就修正或撤回。

以后你让 Codex 做网站、改页面、修 bug、写测试，本质上都离不开这个闭环。

常见错误

错误一：第一次就拿正式项目练手。

更好的做法：先建一个小项目，文件越少越好。

错误二：一上来就让 Codex 修改。

更好的做法：先让它解释文件，确认它读到了真实内容。

错误三：不看 diff。

更好的做法：每次修改后都看一眼删了什么、加了什么。

错误四：看不懂就直接同意。

更好的做法：让 Codex 用普通话解释 diff。

错误五：没有存档就乱改。

更好的做法：动手前先用 Git 记录一次初始版本。

检查清单

完成这一篇后，你应该能勾选：

• 我创建了 hello-codex 练习项目。
• 我创建了 main.py。
• 我用 Git 保存了初始版本。
• 我先让 Codex 解释代码，而不是直接修改。
• 我让 Codex 只修改 main.py。
• 我看过 diff。
• 我知道 - 是旧内容，+ 是新内容。
• 我知道改错了可以让 Codex 修正，或者用 Git 撤回。

小结

第一个任务的重点不是写出多厉害的代码。

重点是跑通这句话：

我提出一个小需求，Codex 修改一个小文件，我看 diff 验收，满意就留下，不满意就退回。

你真正要记住的动作是：审 diff。

只要这个动作养成了，后面再学桌面 App、CLI、权限、MCP、自动化，都会稳很多。