乐于分享
好东西不私藏
夜雨聆风 > > 办公文件 > 第一个 AI 项目:让 Claude Code + Codex 从零开发一个完整 Web 应用

第一个 AI 项目:让 Claude Code + Codex 从零开发一个完整 Web 应用

当前时间： 2026-08-21 06:30:00 分类：办公文件 评论(0)
第一个 AI 项目:让 Claude Code + Codex 从零开发一个完整 Web 应用
前面的文章，我们已经完成了 Ubuntu AI 编程工作站的搭建。
我们已经拥有：
Ubuntu
Git
GitHub
VS Code
Python
Node.js
Claude Code
Codex
Docker
也学习了：
Claude Code
Codex
DeepSeek API
双 AI Agent
Git 工作流
GitHub
AI 编程安全
但是，如果一直停留在“安装”和“配置”阶段，AI 编程就没有真正开始。
所以从这一篇开始，我们正式进入：

AI 实战开发

这一篇，我们不再只讲概念。
我们直接给 AI 一个真实需求：
> 开发一个学生成绩管理 Web 应用。
从一句需求开始，让 Claude Code 和 Codex 一步一步把它变成一个真正可以运行的项目。
---

一、我们到底要做什么？

这次的项目非常适合用来演示 AI 编程。
因为它同时包含：
前端
+
后端
+
数据库
+
API
+
用户交互
+
数据统计
+
测试
最终我们希望得到一个这样的系统：
┌─────────────────────────────┐
│       学生成绩管理系统       │
├─────────────────────────────┤
│                             │
│  学生总数：52                │
│  平均成绩：82.6              │
│  最高成绩：98                │
│                             │
├─────────────────────────────┤
│ 姓名    语文  数学  英语  总分 │
│ 张三     90    95    88   273 │
│ 李四     85    91    92   268 │
│ 王五     78    88    90   256 │
│                             │
└─────────────────────────────┘
同时支持：
添加学生
删除学生
修改成绩
查询学生
成绩统计
成绩排序
数据导出
---

二、为什么选择这个项目？

因为它的复杂度刚刚好。
如果一开始就让 AI 开发：
电商平台
社交网站
大型 AI 应用
项目规模太大，很容易失控。
而学生成绩管理系统：
功能明确
数据结构简单
容易测试
容易理解
非常适合作为第一个 AI 实战项目。
---

三、第一原则：不要一上来就让 AI 写代码

很多人第一次使用 Claude Code 或 Codex，会直接输入：
> 帮我写一个学生管理系统。
然后等待 AI 自动生成。
这种方式看起来很方便，但并不是最好的方法。
更推荐：
需求
↓
分析
↓
设计
↓
技术选型
↓
开发
↓
测试
↓
Review
也就是说：
先让 AI 思考，再让 AI 写代码。
---

四、创建项目目录

进入：
cd ~/projects
创建：
mkdir student-manager
进入：
cd student-manager
初始化 Git：
git init
然后：
git status
确认 Git 工作正常。
---

五、创建第一个 Branch

不要直接在 main 上让 AI 大规模修改。
可以先：
git switch -c feature/initial-project
这样：
main
│
└── feature/initial-project
AI 接下来所有操作都在这个 Branch 中完成。
---

六、让 Claude Code 第一次认识项目

启动：
claude
输入：
> 我准备开发一个学生成绩管理 Web 应用。请先不要修改任何文件。请分析当前项目目录，并告诉我从零开发这个项目需要哪些模块、技术栈和开发步骤。
此时我们不要求它写代码。
我们只要求：
分析。
---

七、让 Claude Code 进行需求拆解

接下来可以输入：
> 请把学生成绩管理系统拆解成具体功能，并按照 MVP 的思路划分第一阶段、第二阶段和第三阶段。第一阶段只保留最核心的功能。
AI 最终可能给出类似：
第一阶段：
1. 学生信息管理
2. 成绩录入
3. 成绩查询
4. 成绩统计
第二阶段：
5. CSV 导出
6. 搜索
7. 排序
8. 分页
第三阶段：
9. 用户登录
10. 权限管理
11. 数据备份
12. 部署
这时候我们选择：
第一阶段先做 MVP。
---

八、什么是 MVP？

MVP 可以理解为：
最小可用产品。
也就是说：
不要一开始做：
登录
权限
消息
AI
数据分析
导出
复杂图表
而是先做：
添加学生
+
录入成绩
+
查询成绩
+
统计成绩
让系统先跑起来。
---

九、为什么 AI 开发尤其需要 MVP？

因为 AI 最大的问题之一就是：
容易做得太多。
例如你告诉 AI：
> 做一个成绩管理系统。
AI 很可能开始：
创建登录系统
创建管理员
创建权限
创建数据库
创建 API
创建图表
创建导出
创建主题切换
最后项目越来越复杂。
所以我们应该告诉 AI：
> 第一阶段只完成 MVP，不要增加需求之外的功能。
这句话非常重要。
---

十、确定技术栈

现在让 Claude Code 给出技术选型。
可以输入：
> 请针对这个 MVP 项目选择一套尽可能简单、适合初学者维护的技术栈。优先使用成熟、轻量、依赖较少的方案，不要为了炫技增加复杂框架。
例如可以采用：
前端：
HTML
CSS
JavaScript
后端：
Python
FastAPI
数据库：
SQLite
测试：
pytest
版本控制：
Git
部署：
Docker
这样整个系统非常轻量。
---

十一、为什么第一版不使用复杂前端框架？

当然可以使用 React、Vue 等现代框架。
但这是一个学习型项目。
我们的目标是：
AI 编程
+
理解项目
+
学习软件工程
如果一开始加入：
React
TypeScript
Vite
Tailwind
状态管理
项目复杂度会明显增加。
所以第一版可以使用：
HTML
CSS
JavaScript
等真正需要的时候再升级。
---

十二、让 Claude Code 生成项目设计文档

这一步非常值得做。
告诉它：
> 请根据刚才确定的技术栈，为项目创建一份 PROJECT.md，说明项目目标、技术栈、目录结构、API 设计、数据库结构、开发阶段和验收标准。暂时不要编写业务代码。
这样项目会出现：
PROJECT.md
以后 Claude Code 和 Codex 都可以读取这个文件。
---

十三、为什么需要项目文档？

因为 AI 每次启动并不应该完全依赖聊天上下文。
项目真正重要的信息应该存在项目中：
PROJECT.md
README.md
docs/
这样：
Claude Code
↓
读取 PROJECT.md
Codex
↓
读取 PROJECT.md
两个 Agent 就有了：
共同的项目“说明书”。
---

十四、建立项目规则

我们还可以创建：
AGENTS.md
里面写：
项目规则：
1. 使用 Python 3。
2. 后端使用 FastAPI。
3. 数据库使用 SQLite。
4. 不要随意增加第三方依赖。
5. 所有新功能必须增加测试。
6. 不要修改数据库结构，除非得到确认。
7. 不要删除现有测试。
8. 修改完成后运行全部测试。
9. 不要提交 API Key。
10. 不要修改与当前任务无关的文件。
这样以后 AI 每次进入项目，都能看到这些约束。
---

十五、AI 编程中的“项目规则”非常重要

可以把它理解为：
用户要求
↓
项目规则
↓
AI 执行
例如：
用户：
> 增加学生搜索功能。
AI 不应该随便：
更换数据库
更换框架
修改前端架构
因为项目规则已经规定：
尽量复用现有代码
不要增加不必要依赖
这会明显减少 AI“自由发挥”。
---

十六、现在让 Codex 开始创建项目

退出 Claude Code：
exit
启动：
codex
告诉 Codex：
> 请读取 PROJECT.md 和 AGENTS.md。按照第一阶段 MVP 需求创建项目基础结构。先完成项目骨架、数据库模型和基础 API，不要实现第二阶段和第三阶段功能。完成后运行测试。
这时候 Codex 开始真正写代码。
---

十七、Codex 可能创建这样的目录

例如：
student-manager/
│
├── app/
│   ├── main.py
│   ├── database.py
│   ├── models.py
│   └── routes/
│
├── tests/
│
├── static/
│
├── templates/
│
├── PROJECT.md
├── AGENTS.md
├── README.md
├── requirements.txt
└── .gitignore
这时候不要急着评价代码。
先看：
git status
然后：
git diff
---

十八、第一次检查 AI 的代码

重点看：
有没有生成奇怪的文件？
有没有修改规则文件？
有没有增加不必要的依赖？
数据库设计是否符合要求？
代码结构是否清晰？
如果发现：
AI 自己安装了十几个依赖
可以直接要求：
> 请重新检查依赖，只保留当前 MVP 必需的依赖。
---

十九、安装项目依赖

如果是 Python 项目：
python3 -m venv .venv
激活：
source .venv/bin/activate
然后：
pip install -r requirements.txt
之后运行项目。
具体启动命令应该以项目 README 中实际生成的命令为准。
例如可能是：
uvicorn app.main:app --reload
---

二十、第一次启动项目

浏览器打开本地地址。
例如：
http://127.0.0.1:8000
如果能看到：
学生成绩管理系统
说明：
我们的第一个 AI Web 项目已经启动。
这时候不要急着继续开发。
先手动测试。
---

二十一、手动测试第一版

例如：
添加：
张三
语文：90
数学：95
英语：88
然后：
查询张三
看看是否可以正确显示：
总分：273
然后继续：
添加李四
删除李四
修改张三数学成绩
观察系统是否正常。
---

二十二、为什么一定要人工测试？

因为：
测试通过
并不代表：
用户体验正常
例如自动测试可能验证：
数据库成功插入
但浏览器中可能出现：
按钮无法点击
页面样式错误
中文乱码
数据没有刷新
所以：
自动测试
+
人工测试
缺一不可。
---

二十三、让 Codex 编写测试

如果人工测试发现基本功能正常，可以告诉 Codex：
> 请为当前 MVP 的核心功能补充完整测试，包括学生新增、查询、修改、删除、成绩计算以及异常输入。不要修改业务逻辑，只增加必要测试。
然后运行：
python3 -m pytest
例如：
18 passed
说明当前测试基本通过。
---

二十四、让 Claude Code 进行第一次 Code Review

启动：
claude
告诉它：
> 请阅读当前项目代码，并对 MVP 进行一次完整 Code Review。重点检查项目结构、API 设计、数据库操作、异常处理、输入验证、安全问题以及代码可维护性。不要修改代码，只输出问题和建议，并按照高、中、低风险分类。
这时候 Claude Code 就成为：
项目 Reviewer。
---

二十五、为什么 Review 不直接让 AI 修改？

因为：
开发者
↓
写代码
Reviewer
↓
发现问题
如果 Reviewer 同时修改代码，就很难判断：
到底修改了什么？
为什么修改？
是不是引入了新问题？
所以推荐：
发现问题
↓
输出报告
↓
人确认
↓
Codex 修复
---

二十六、让 Codex 修复问题

将 Review 结果交给 Codex：
> 请根据 Code Review 报告修复高风险和中风险问题。不要处理低风险的非必要重构。每修改一个问题，都增加对应测试。完成后运行全部测试。
这时候形成：
Codex
↓
开发
Claude Code
↓
Review
Codex
↓
修复
这就是我们之前建立的双 Agent 工作流真正落地。
---

二十七、增加前端页面

后端稳定以后，再告诉 Codex：
> 现在为学生成绩管理 API 增加一个简单的 Web 前端。要求界面简洁、响应式，支持学生列表、添加学生、修改成绩和删除学生。不要引入复杂前端框架。
Codex 开始：
HTML
+
CSS
+
JavaScript
最终形成：
浏览器
↓
HTML/CSS/JS
↓
FastAPI
↓
SQLite
---

二十八、这时候我们已经有了完整的 Web 架构

可以理解成：
┌────────────────────┐
│      浏览器         │
│  HTML/CSS/JS       │
└─────────┬──────────┘
│
│ HTTP
↓
┌────────────────────┐
│     FastAPI        │
│      后端 API       │
└─────────┬──────────┘
│
↓
┌────────────────────┐
│      SQLite        │
│       数据库        │
└────────────────────┘
这已经是一个完整的 Web 应用。
---

二十九、让 AI 增加成绩统计

下一步可以提出：
> 增加成绩统计功能，包括学生总数、平均分、最高分和最低分。统计数据应该通过后端 API 获取，并在前端展示。
这时候 AI 需要同时修改：
后端
+
API
+
前端
这就是一个非常典型的跨模块任务。
---

三十、不要一次给 AI 十个功能

例如不要一次说：
> 增加登录、权限、成绩统计、CSV、Excel、图表、主题切换、搜索、分页、Docker。
更好的方式是：
任务 1
↓
完成
↓
测试
任务 2
↓
完成
↓
测试
任务 3
↓
完成
↓
测试
这就是：
小步迭代。
---

三十一、每完成一个功能就 Commit

例如：
git add .
git commit -m "feat: add student management API"
然后：
git add .
git commit -m "feat: add student web interface"
再：
git add .
git commit -m "feat: add score statistics"
这样以后如果：
统计功能
↓
出现问题
可以很容易回退。
---

三十二、什么时候应该让 Git 分支合并？

假设：
main
是稳定版本。
现在：
feature/initial-project
已经完成：
项目结构
+
后端
+
前端
+
测试
确认：
自动测试通过
+
人工测试通过
+
Claude Code Review 通过
然后：
feature/initial-project
↓
Pull Request
↓
Review
↓
Merge
↓
main
这样第一阶段 MVP 就正式完成。
---

三十三、把项目推送到 GitHub

例如：
git push -u origin feature/initial-project
然后在 GitHub 中创建 Pull Request。
PR 描述可以写：

本次更新

完成学生成绩管理系统 MVP。

功能

- 学生信息管理
- 成绩录入
- 成绩查询
- 成绩修改
- 成绩统计
- Web 页面

测试

全部测试通过。

Review

已完成 AI Code Review 和人工检查。
---

三十四、让 GitHub Actions 自动测试

接下来，我们可以增加：
.github/
└── workflows/
└── test.yml
让 GitHub 在每次 Push 或 Pull Request 时自动运行测试。
最终：
Codex
↓
修改代码
↓
git push
↓
GitHub
↓
自动测试
如果测试失败：
GitHub
↓
报告失败
↓
Codex 分析
↓
修复
↓
Push
这样就形成了一个自动反馈循环。
---

三十五、最后使用 Docker 打包

当项目开发完成后，我们可以让 Codex：
> 请为当前项目编写 Dockerfile，并确保项目可以在干净环境中启动。不要修改业务逻辑。
然后：
docker build -t student-manager .
启动：
docker run -p 8000:8000 student-manager
如果能够正常运行：
浏览器
↓
Docker
↓
FastAPI
↓
SQLite
我们的项目就完成了第一次容器化。
---

三十六、从一句话到完整项目

现在回头看看最开始的需求：
> “帮我做一个学生成绩管理系统。”
经过一系列步骤以后：
一句需求
↓
需求分析
↓
MVP
↓
技术选型
↓
项目文档
↓
Codex 开发
↓
自动测试
↓
Claude Code Review
↓
Bug 修复
↓
前端
↓
API
↓
数据库
↓
Git
↓
GitHub
↓
GitHub Actions
↓
Docker
最终变成：
一个真正可以运行的 Web 应用。
这才是 AI 编程最值得学习的地方。
---

三十七、AI 并没有代替开发者

整个过程中，你会发现：
AI 做了大量工作。
但是仍然有一些事情必须由人决定：
项目做什么？
↓
为什么做？
↓
技术方案是否合理？
↓
AI 有没有做错？
↓
什么时候停止开发？
↓
代码能不能进入 main？
所以 AI 编程并不是：
> “以后不需要程序员了。”
更准确的理解是：
> 程序员正在从“代码执行者”，逐渐变成“AI 开发流程的设计者和管理者”。
---

三十八、AI 编程真正的核心能力

如果你准备长期学习 AI 编程，我建议重点培养这几个能力：
第一：需求表达
知道：
我要做什么
---
第二：任务拆解
把：
一个大需求
拆成：
多个小任务
---
第三：代码阅读
AI 写出来以后：
你要看得懂
---
第四：测试
知道：
怎么证明 AI 写对了
---
第五：Git
知道：
怎么保存
怎么比较
怎么回退
怎么协作
---
第六：安全
知道：
什么能给 AI
什么不能给 AI
---
第七：Review
知道：
AI 的方案是否真的合理
这些能力，比单纯记住几个 AI 命令更加重要。
---

三十九、这一篇真正学到的是什么？

表面上，我们做的是：
学生成绩管理系统。
但实际上，我们学习的是一套完整的方法：
需求
↓
MVP
↓
设计
↓
AI 开发
↓
测试
↓
Review
↓
Git
↓
GitHub
↓
CI
↓
Docker
以后你做的项目可以不是学生成绩管理系统。
也可以是：
个人博客
在线记账系统
课程管理系统
图书管理系统
AI 聊天网站
个人知识库
自动化工具
流程仍然可以复用。
---

四十、总结

到这里，我们终于真正完成了这个系列的第一次完整 AI 项目实战。
整个过程可以浓缩成：
用户提出需求
↓
Claude Code
需求分析 + 技术设计
↓
Codex
项目开发
↓
自动测试
↓
Claude Code
Code Review
↓
Codex
修复问题
↓
Git
版本管理
↓
GitHub
代码托管
↓
GitHub Actions
自动测试
↓
Docker
容器化运行
↓
人工最终确认
而这也是我们整个系列一直想要建立的核心理念：
> AI 不是简单的代码生成器，而是软件开发团队中的一个新成员。
我们真正要学习的，不是如何让 AI 一次写出几千行代码，而是：
如何把一个模糊的想法，拆解成 AI 可以执行、测试、Review 和交付的完整工程流程。
---

下一篇预告

下一篇，我们继续在这个项目上升级。

《AI 项目进阶：让 Claude Code + Codex 开发真正的登录、权限与数据库系统》

这一篇我们会开始面对真实项目中更加重要的问题：
用户登录
↓
密码加密
↓
Session / Token
↓
权限管理
↓
管理员
↓
普通用户
↓
数据库设计
↓
API 权限验证
↓
前端登录状态
同时也会重点讲一个非常重要的问题：
> 如何让 AI 写“涉及密码和用户权限”的代码，而不会把项目安全性搞崩。
从这一篇开始，我们的项目将从一个简单的练习项目，逐渐向真正的生产级 Web 应用开发思路靠近。