现代软件工程实践:AI 编程智能体、代码质量与工程协作
基于 MIT The Missing Semester 三个主题的系统化教程
- 第一部分:Agentic Coding(AI 编程智能体)
- 第二部分:Beyond the Code(软件工程沟通与协作)
- 第三部分:Code Quality(代码质量与自动化工程实践)
导言:从编写代码到交付可靠的软件
传统计算机课程通常比较关注算法、数据结构、编程语言和操作系统。但是,在真实的软件开发工作中,仅仅掌握这些知识是不够的。
一个软件工程师还需要解决以下问题:
- 如何快速理解一个陌生的软件项目?
- 如何借助 AI 完成代码开发,同时保证代码正确?
- 如何发现代码中的潜在错误?
- 如何自动执行代码检查和测试?
- 如何让其他开发者理解自己的代码?
- 如何与团队成员协作开发?
- 如何提交高质量的代码修改?
- 如何确保软件能够长期维护?
这三个主题共同回答了这些问题。
1. 软件工程的三个层次
我们可以将现代软件工程划分为三个层次。
第一层:Software Development(软件开发)
核心问题:如何把需求转化为代码?
涉及:
- 需求理解
- 代码阅读
- 功能实现
- AI 辅助编程
- 代码重构
对应第一部分 Coding Agents。
第二层:Software Quality Assurance(软件质量保证)
核心问题:如何确保代码正确、稳定和可靠?
涉及:
- 代码格式化
- 静态分析
- 类型检查
- 自动化测试
- 持续集成
对应第三部分 Code Quality。
第三层:Software Engineering Collaboration(软件工程协作)
核心问题:如何让不同的人共同理解、开发和维护软件?
涉及:
- 技术文档
- 代码注释
- Git 提交记录
- Bug Report
- Pull Request
- Code Review
- 开源社区协作
对应第二部分 Beyond the Code。
三个层次不是独立的。
例如,当 AI 修改了一段代码后:
- Coding Agent 负责实现修改。
- Code Quality 工具负责验证修改。
- Code Review 负责判断修改是否值得合并。
- 技术文档负责记录修改背后的设计决策。
2. 本教程的贯穿案例
为了避免知识点彼此孤立,我们将围绕一个小型 Python 项目进行学习。
项目名称:Markdown Link Extractor
目标:开发一个命令行工具,从 Markdown 文件或网络资源中提取链接。
最终项目结构:
markdown-link-extractor/
│
├── AGENTS.md
├── README.md
├── pyproject.toml
├── uv.lock
├── .gitignore
├── .pre-commit-config.yaml
│
├── src/
│ └── link_extractor/
│ ├── __init__.py
│ └── cli.py
│
├── tests/
│ ├── test_extract.py
│ └── test_cli.py
│
└── .github/
└── workflows/
└── ci.yml
我们将逐步完成:
- 使用 AI 编程智能体开发程序。
- 为程序添加类型注解和自动化测试。
- 配置 Formatter 和 Linter。
- 配置 Git Pre-commit Hooks。
- 配置 GitHub Actions。
- 编写 README 和技术文档。
- 创建 Git Commit 和 Pull Request。
- 通过 Code Review 完成软件交付。
第一部分:Agentic Coding(AI 编程智能体)
第 1 章 理解 AI 编程智能体
1.1 从传统编程到 AI 辅助编程
传统软件开发通常遵循以下过程:
需求
↓
程序员分析问题
↓
编写代码
↓
运行程序
↓
发现错误
↓
修改代码
↓
重新测试
随着大语言模型的发展,程序员可以将部分开发任务交给 AI。
例如:
- 解释一个陌生项目。
- 根据需求生成函数。
- 修改已有代码。
- 编写单元测试。
- 修复类型检查错误。
- 重构大型模块。
- 分析 Git 修改记录。
但需要区分三种 AI 编程方式。
1.1.1 AI Autocomplete(智能代码补全)
这是最基础的 AI 编程辅助方式。
例如:
def calculate_average(numbers):
AI 根据上下文预测后续代码:
return sum(numbers) / len(numbers)
特点:
- 以局部代码补全为主。
- 通常不需要复杂的任务规划。
- 适合减少重复编码。
- 程序员仍然主导整个开发过程。
1.1.2 Inline Chat(代码编辑器中的 AI 对话)
程序员可以选中一段代码,让 AI:
- 解释代码。
- 优化代码。
- 增加注释。
- 修改函数。
- 转换编程语言。
例如:
将这个函数重构为三个独立函数,
分别负责数据验证、数据处理和结果输出。
AI 根据要求生成修改建议或直接修改选中的代码。
1.1.3 Coding Agent(AI 编程智能体)
Coding Agent 的能力更进一步。
它不仅生成代码,还可以操作开发环境。
例如:
请分析这个项目。
找到处理用户登录的代码,
增加密码长度验证,
补充相应的单元测试,
运行测试和类型检查,
直到所有检查通过。
Agent 可以自主执行一系列操作:
- 查找项目文件。
- 阅读相关代码。
- 确定需要修改的位置。
- 修改代码。
- 创建测试。
- 执行测试。
- 根据错误继续修改。
- 总结最终结果。
这就是 Agentic Coding。
1.2 Coding Agent 的核心架构
要理解 Coding Agent,首先需要理解它不是一个单独的语言模型,而是由多个部分构成的系统。
1.2.1 LLM:大语言模型
LLM(Large Language Model)是 Coding Agent 的核心推理和文本生成组件。
从课程采用的高层模型来看:
给定输入字符串,模型根据训练得到的概率分布预测后续 Token。
可以写成:
[
P(y\mid x)
]
其中:
- (x):输入 Prompt。
- (y):模型生成的输出。
- (P(y\mid x)):给定输入时生成某个输出的概率。
在编程任务中:
输入可以是:
- 用户的需求。
- 项目源代码。
- 终端输出。
- 历史对话。
- 外部文档。
输出可以是:
- 解释。
- Python 代码。
- 修改建议。
- 工具调用请求。
需要注意,LLM 的输出是概率生成结果,并不意味着它已经通过程序运行验证。
1.2.2 Agent Harness:智能体运行框架
Agent Harness 是连接语言模型与外部工具的程序。
它负责:
- 将上下文发送给模型。
- 识别模型生成的工具调用请求。
- 执行对应工具。
- 将执行结果反馈给模型。
- 管理对话和工具调用过程。
- 根据权限策略决定是否需要用户确认。
例如,模型可能生成一个执行测试的工具调用请求:
Tool: Terminal
Command:
pytest tests/
Harness 负责执行命令,并将结果返回模型。
模型随后根据结果决定下一步。
1.2.3 Tools:外部工具
常见工具包括:
| 工具类别 |
典型功能 |
| File Tools |
读取、创建和修改文件 |
| Shell |
执行终端命令 |
| Search |
搜索项目和外部文档 |
| Git |
查看版本历史和代码差异 |
| Testing |
执行自动化测试 |
| Type Checking |
执行类型检查 |
| Browser |
浏览网页和在线文档 |
1.2.4 Agent Loop:智能体循环
Coding Agent 最重要的工作机制是反复执行:
Observe → Think → Act → Observe
即:
观察 → 分析 → 行动 → 再次观察。
例如:
用户提出需求
↓
Agent 阅读项目
↓
Agent 分析代码结构
↓
Agent 修改代码
↓
Agent 运行测试
↓
测试失败?
↙ ↘
是 否
↓ ↓
分析错误 汇报结果
↓
重新修改
↓
重新测试
这就是为什么允许 Agent 运行测试工具特别重要。
如果 Agent 只能生成代码,却不能获得测试反馈,它就很难建立可靠的自动修正循环。
第 2 章 如何正确使用 Coding Agent
2.1 从模糊需求到明确任务
一个常见错误是只告诉 Agent:
帮我优化这个项目。
这个需求过于模糊。
Agent 不知道:
- 哪些地方需要优化?
- 是性能还是可维护性?
- 是否允许改变 API?
- 是否可以修改项目结构?
- 如何判断优化成功?
更好的方法是把需求拆分为五个部分。
任务描述模板
Task:
需要完成什么任务?
Context:
当前项目是什么情况?
涉及哪些文件和功能?
Constraints:
有哪些不能违反的限制?
Acceptance Criteria:
什么情况下认为任务完成?
Verification:
应该运行哪些检查?
例如:
Task:
将现有 Markdown 链接提取脚本改造成命令行程序。
Context:
当前程序通过 urllib 下载 Markdown 文件,
使用正则表达式提取链接。
Constraints:
1. 使用 Python 标准库。
2. 保留现有提取逻辑。
3. 不引入不必要的第三方依赖。
4. 使用类型注解。
Acceptance Criteria:
1. 支持通过命令行传入 URL。
2. 支持将结果输出到终端。
3. 支持将结果保存到文件。
4. 网络请求失败时给出清晰错误信息。
Verification:
运行 pytest。
运行 mypy。
运行 ruff。
这种任务描述比简单的自然语言要求更容易得到可靠结果。
2.2 实践:让 Agent 改造一个 Python 程序
原课程给出了一个示例。
首先有一个简单程序:
from urllib.request import urlopen
import re
def download_contents(url: str) -> str:
with urlopen(url) as response:
return response.read().decode("utf-8")
def extract(content: str) -> list[str]:
pattern = r"\[.*?\]\((.*?)\)"
return re.findall(pattern, content)
print(
extract(
download_contents(
"https://example.com/document.md"
)
)
)
这个程序有几个问题:
- URL 被写死在代码中。
- 无法通过命令行传入不同 URL。
- 缺少完善的错误处理。
- 没有定义清晰的程序入口。
- 还没有建立自动化测试。
现在让 Coding Agent 将其改造成命令行程序。
目标结构:
import argparse
import re
from urllib.request import urlopen
def download_contents(url: str) -> str:
with urlopen(url, timeout=10) as response:
return response.read().decode("utf-8")
def extract(content: str) -> list[str]:
pattern = r"\[.*?\]\((.*?)\)"
return re.findall(pattern, content)
def main() -> None:
parser = argparse.ArgumentParser()
parser.add_argument(
"url",
help="Markdown document URL"
)
args = parser.parse_args()
content = download_contents(args.url)
links = extract(content)
for link in links:
print(link)
if __name__ == "__main__":
main()
运行:
python main.py https://example.com/document.md
这里使用了 Python 的 argparse 模块。
它负责解析命令行参数。
例如:
python main.py --help
可以显示程序使用说明。
进一步改进
可以继续要求 Agent:
请进一步改进这个程序:
1. 增加输出文件参数 --output。
2. 网络请求失败时返回非零退出状态。
3. 对输入 URL 进行基本检查。
4. 为 extract 编写单元测试。
5. 使用 mypy 检查类型。
6. 使用 Ruff 检查代码质量。
这里需要特别注意:
课程中的正则表达式是一个简单的 Markdown 链接提取示例,不是完整的 Markdown 解析器。对于包含嵌套括号、转义字符等复杂情况的 Markdown,需要更完善的解析方案。
2.3 让 Agent 形成闭环
最重要的不是让 AI 生成更多代码,而是让它能够验证自己的修改。
推荐工作方式:
明确需求
↓
阅读代码
↓
制定修改方案
↓
执行修改
↓
运行测试
↓
检查失败信息
↓
修改
↓
再次验证
可以使用如下 Prompt:
请不要只根据代码阅读结果判断任务完成。
你需要:
1. 修改相关文件。
2. 运行项目已有的测试。
3. 运行类型检查。
4. 运行 Linter。
5. 检查失败原因。
6. 修复你造成的问题。
7. 再次执行全部检查。
最后列出:
- 修改了哪些文件
- 解决了什么问题
- 执行了哪些检查
- 哪些检查通过
- 还有哪些未解决的问题
注意:Agent 声称检查通过,不等于检查确实通过。需要查看实际终端结果。
第 3 章 Coding Agent 的主要应用场景
3.1 Feature Implementation:新功能开发
任务:为一个已有程序增加功能。
例如:
为现有用户管理系统增加 CSV 导出功能。
要求:
- 支持选择导出字段。
- 支持 UTF-8 编码。
- 不修改原有查询 API。
- 为正常情况和异常情况增加测试。
适用场景:
- 增加功能。
- 编写重复代码。
- 扩展 API。
- 增加命令行参数。
- 实现数据处理逻辑。
3.2 Error Fixing:错误修复
当编译器、Linter、Type Checker 或测试出现错误时,可以将错误信息交给 Agent。
例如:
运行 mypy 后出现以下错误:
Incompatible return value type
请分析原因并修复。
不要通过简单关闭类型检查规则来消除错误。
为什么要避免只关闭规则?
因为这可能只是隐藏了问题,并没有真正修复问题。
3.3 Refactoring:代码重构
重构是改善代码内部结构,而尽量不改变外部行为。
例如:
原本有一个过长的函数:
def process_user(data):
pass
可以拆分为:
def validate_user(data):
pass
def clean_user(data):
pass
def save_user(data):
pass
def process_user(data):
validate_user(data)
clean_user(data)
save_user(data)
重构之后,应该使用测试验证原有功能没有被破坏。
3.4 Code Review:AI 辅助审查
可以让 Agent 检查最近一次 Commit 的修改:
Review all changes since the last commit.
Focus on:
1. Correctness bugs.
2. Security vulnerabilities.
3. Missing error handling.
4. Performance issues.
5. Missing tests.
For each finding, provide:
- File and line number.
- Explanation.
- Potential impact.
- Suggested fix.
Do not report purely stylistic preferences.
AI 的审查结果应作为候选问题,而不是最终结论。
3.5 Code Understanding:理解陌生项目
当你接触一个大型代码库时,可以让 Agent:
- 识别项目入口。
- 解释模块关系。
- 找出关键数据结构。
- 追踪函数调用关系。
- 解释一个功能的执行路径。
建议使用逐步追问,而不是一次要求它解释整个仓库。
例如:
第一步:
请识别项目的主要入口文件。
第二步:
请追踪用户登录请求的调用路径。
第三步:
请解释认证中间件的工作机制。
第四步:
请指出这一实现可能存在的安全风险。
3.6 Shell as an Interface:自然语言驱动终端
Agent 还可以将自然语言转换为 Shell 命令。
例如:
找到项目中所有超过 500 行的 Python 文件。
Agent 可能使用:
find . -name "*.py" -exec wc -l {} \;
但是,Shell 命令具有很强的操作能力。
涉及删除文件、修改权限、覆盖数据、访问网络和读取秘密信息的命令,必须谨慎审查。
3.7 Vibe Coding:自然语言驱动应用开发
Vibe Coding 适合:
- 小型原型。
- 概念验证。
- 个人工具。
- 快速试验。
- 交互界面草稿。
不适合直接将未经理解和验证的生成结果投入关键生产系统。
第 4 章 进阶智能体工程
4.1 Reusable Prompts:可复用提示词
如果你经常要求 Agent 做代码审查,可以把任务要求保存为模板。
例如:
你是一个 Python Code Review Agent。
请重点检查:
1. 逻辑正确性。
2. 异常处理。
3. 类型安全。
4. 资源管理。
5. 安全问题。
6. 测试覆盖。
请优先报告高风险问题。
不要仅仅为了个人风格提出修改建议。
这样可以减少重复编写 Prompt 的时间。
4.2 Parallel Agents:并行智能体
多个 Agent 可以同时完成不同任务。
例如:
| Agent |
工作 |
| Agent A |
实现 API |
| Agent B |
编写测试 |
| Agent C |
阅读技术文档 |
| Agent D |
审查安全风险 |
但要避免多个 Agent 同时修改相同文件。
课程推荐使用 Git Worktree 隔离工作目录。
例如:
git worktree add ../project-api feature-api
git worktree add ../project-tests feature-tests
这样不同工作目录可以对应不同分支。
4.3 MCP:Model Context Protocol
MCP 是连接 AI 应用与外部工具、数据源的开放协议。
例如,一个支持 MCP 的 Coding Agent 可以通过相应服务:
- 读取项目文档。
- 查询数据库。
- 访问 Notion。
- 与其他工作系统交互。
MCP 解决的是模型如何通过标准化接口访问外部工具和上下文的问题。
它不是一个新的语言模型,也不是编程语言。
4.4 Context Management:上下文管理
课程重点介绍四种方式。
Clear Context
对于完全不同的任务,开始新的对话。
避免无关历史干扰当前任务。
Rewind
当 Agent 沿着错误方向执行时,回退到之前的状态。
比不断叠加修正 Prompt 更有效。
Compaction
将较长的历史压缩为摘要。
保留重要信息,减少上下文消耗。
llms.txt
教材介绍了 /llms.txt 这一提议标准。
它的目标是提供适合语言模型阅读的文档入口。
例如,一个工具的文档可能包含:
https:
它可以帮助 Agent 更高效地获取相关文档,但具体是否提供以及内容质量取决于项目。
AGENTS.md 是项目级指导文件。
例如:
# AGENTS.md
## Project
Python 3.12 project.
## Coding Standards
- Use type annotations.
- Use Ruff for formatting.
- Use Ruff for linting.
## Testing
Run pytest before completing a task.
## Restrictions
- Do not modify generated files.
- Do not commit secrets.
- Preserve public APIs unless explicitly requested.
它可以帮助 Agent 在多个任务和会话中遵循统一项目规范。
4.6 Skills 与 Subagents
Skill 是专门工作流程的封装。
Subagent 是负责特定任务的子智能体。
例如:
Main Agent
|
+
|
+
|
+
它们可以让主 Agent 将工作委派给专门的子流程。
但不同产品对 Skills 和 Subagents 的支持方式不完全相同。
第 5 章 AI 编程的局限与风险
5.1 概率生成不等于程序正确
AI 可能生成:
- 不存在的 API。
- 错误的依赖用法。
- 不符合需求的逻辑。
- 不安全的代码。
- 看似正确但实际失败的测试。
5.2 Debugging Spiral:调试循环
有时 Agent 会:
- 修改代码。
- 运行测试。
- 发现错误。
- 修改另一个位置。
- 引入新的错误。
- 再次尝试。
这种过程可能不断扩大修改范围。
解决方法:
- 要求先定位根因。
- 控制修改范围。
- 查看 Git Diff。
- 每次修改后运行相关测试。
- 必要时回退。
- 不要让 Agent 无限制地重复尝试。
5.3 Privacy:隐私风险
课程提醒,许多 AI 编程工具默认使用云端模型。
可能被发送到云端的信息包括:
- 源代码。
- 项目文件。
- 提示词。
- 终端输出。
- 交互历史。
因此,使用前应该检查工具的数据处理方式、企业政策和隐私要求。
5.4 Overreliance:过度依赖
如果程序员只负责提出需求,完全不理解生成的代码,就很难承担长期维护责任。
尤其在学习阶段,完全让 AI 代替自己思考,可能使你获得了一个程序,却没有获得相应的编程能力。
最终原则:AI 可以承担执行任务的工作,但程序员必须承担理解、验证和决策的责任。
第二部分:Beyond the Code(软件工程沟通与协作)
第 6 章 软件工程为什么不仅仅是编程?
软件工程师的工作不仅包括编写程序,还包括与其他工程师进行持续交流。
真实项目中,你需要:
- 解释系统如何工作。
- 了解其他团队的需求。
- 阅读他人的代码。
- 参与技术决策。
- 报告错误。
- 审查代码。
- 维护已有系统。
课程将工程沟通大致分成两类:
- One-way Communication:单向沟通。
- Two-way Communication:双向沟通。
单向沟通主要通过文档、注释和提交信息完成。
双向沟通主要通过讨论、Issue、PR、Review 和技术交流完成。
第 7 章 One-way Communication:单向技术沟通
7.1 为什么需要单向沟通?
假设你今天完成了一个复杂的功能。
六个月以后,另一位程序员接手这个项目。
他可能不知道:
- 为什么使用当前算法?
- 为什么选择这个数据结构?
- 为什么某个参数是 1492?
- 为什么没有采用另一种实现?
- 哪些部分存在尚未解决的限制?
如果没有记录,这些知识就会随着开发者离开项目而消失。
因此,技术文档的一个核心任务是保存决策背后的原因。
7.2 Code Comments:代码注释
课程强调:
好注释解释 Why,而不是重复 What。
错误示例:
counter += 1
正确性或设计理由示例:
后者记录了代码中不容易直接看出的约束。
值得记录的七类注释
1. TODO
标记尚未完成的工作。
不好的写法:
更好的写法:
2. References
记录算法、论文或外部规范的来源。
例如:
正式项目中最好引用稳定的文档版本或永久链接。
3. Correctness Arguments
解释复杂代码为什么正确。
4. Hard-learned Lessons
记录不容易发现的问题。
例如:
5. Rationale for Constants
解释魔法数字。
MAX_BATCH_SIZE = 128
6. Load-bearing Choices
解释为什么某个实现细节不能随便改变。
7. Why Not
解释为什么没有采用看起来更简单的方案。
7.3 README:项目说明文档
README 是项目的入口。
推荐结构:
# Project Name
## What does this project do?
## Why should you use it?
## Usage
## Installation
## Configuration
## Development
## Testing
## License
核心顺序:
What → Why → Usage → Installation
先让读者理解项目价值,再让读者学习使用和安装。
README 的质量标准
一个好的 README 应当:
- 能快速说明项目目标。
- 有可以直接理解的使用示例。
- 给出清楚的安装步骤。
- 说明必要的配置。
- 指明项目限制。
- 给出开发和测试方法。
- 不用大量无关文字淹没核心信息。
7.4 Commit Messages:提交说明
Git Commit 不只是保存代码变化,也是记录项目演进历史。
不好的提交:
fix bug
update files
change code
这些内容无法帮助未来的开发者理解修改原因。
课程建议使用:
Problem → Solution → Implications
示例
Prevent duplicate payment processing
Problem:
Network retries may submit the same payment
request multiple times.
Solution:
Use an idempotency key to identify repeated
requests and reuse the existing result.
Implications:
Callers must now provide a stable idempotency key.
如何组织复杂 Commit?
一个 Commit 应当尽量代表一个逻辑完整的修改。
例如:
Commit 1: Add authentication validation
Commit 2: Add authentication unit tests
Commit 3: Update authentication documentation
不要把无关重构、格式化和功能开发混在一个提交中。
使用:
git add -p
可以交互式选择文件中的不同修改块。
这有利于:
- 审查。
- 回滚。
- 使用 git bisect 定位问题。
- 理解项目历史。
使用 LLM 生成 Commit Message
课程指出一个重要问题:
如果只给 LLM 一个 Git Diff,它通常只能知道 What,不知道 Why。
因此可以让模型:
根据当前 Diff 编写 Commit Message。
重点解释:
1. 修改所解决的问题。
2. 选择该方案的原因。
3. 考虑过哪些替代方案。
4. 修改带来的影响。
如果缺少必要背景,请先向我提问。
如果 Agent 本身参与了开发,它通常能够访问此前的需求和设计讨论,因此更容易生成准确的提交说明。
第 8 章 Collaboration:软件工程协作
8.1 软件开发中的参与者
开源项目中通常存在三类群体:
- Users:使用软件的人。
- Contributors:参与贡献的人。
- Maintainers:负责项目长期维护的人。
课程指出,通常用户数量远大于贡献者数量,而贡献者数量又远大于维护者数量。
因此,维护者的时间是一种稀缺资源。
一个贡献是否值得被接受,不仅取决于它能否解决问题,还取决于它是否值得维护者投入时间。
这就是 High Signal-to-Noise Ratio(高信噪比)的重要性。
8.2 Bug Report:高质量错误报告
一个好的 Bug Report 应当包括:
| 内容 |
说明 |
| Environment |
操作系统、版本、配置 |
| Expected Behavior |
预期行为 |
| Actual Behavior |
实际行为 |
| Reproduction Steps |
复现步骤 |
| Previous Attempts |
已经尝试的排查方法 |
示例:
# Bug: CSV export fails for empty input
## Environment
Python 3.12
Ubuntu 24.04
Application v1.2.0
## Expected Behavior
An empty CSV should produce a valid output file
containing the header row.
## Actual Behavior
The program raises IndexError.
## Steps to Reproduce
1. Create an empty input.csv.
2. Run the export command.
3. Observe the exception.
## What I Tried
The issue does not occur with non-empty CSV files.
8.3 Search Existing Issues
提交 Issue 前,先检查:
- 是否已经有人报告相同问题?
- 是否存在正在讨论的解决方案?
- 是否有相关的 Pull Request?
- 是否有项目文档解释该行为?
重复创建 Issue 会增加维护成本。
如果已经存在相关讨论,通常更好的方式是补充有价值的信息。
8.4 Minimal Reproducible Example
最小可复现示例是帮助维护者定位问题的重要工具。
例如,原本有一个大型应用:
10000 lines of code
你逐步删除不相关模块,最后得到:
def parse_value(value):
return value[0]
然后发现输入空字符串时会引发问题。
这比提交整个大型项目更有助于分析根因。
8.5 Issue 的沟通礼仪
课程特别提醒:
- 不要频繁催促维护者。
- 不要反复发布没有新增信息的“me too”。
- 不要只复制终端输出。
- 应该先搜索已有问题。
- 如果等待一段时间没有回复,可以礼貌跟进。
- 如果能够复现问题,尽量提供最小示例。
维护者可能是志愿者,不能假设他们随时有时间响应。
参与开源项目之前,应阅读:
CONTRIBUTING.md
它通常规定:
- 如何创建开发分支。
- 如何运行测试。
- 代码风格要求。
- PR 格式。
- 提交信息要求。
- 项目开发流程。
还需要注意项目许可证。
例如,某些 Copyleft 许可证会对衍生作品的发布方式产生要求。贡献之前应该了解许可证对代码使用和分发的影响。
如果发现安全漏洞,不应直接公开发布详细利用信息。应该优先通过项目的安全披露渠道联系维护者,给予合理修复时间。
8.7 Pull Request:提交代码贡献
一个好的 PR 应当满足:
- 修改范围明确。
- 尽量避免无关变化。
- 解释为什么需要修改。
- 解释为什么采用当前实现。
- 提供测试方式。
- 指出需要审查的重点。
如果一个功能确实需要很多相关文件的修改,可以使用较大的 PR,但应该保持 Commit 组织清晰,使维护者能够逐步审查。
AI 生成的 PR
课程特别提醒:
AI 可以快速生成代码,但不能因此降低贡献者的责任。
如果提交者自己无法解释代码,维护者就需要承担额外的理解、审查和维护成本。
因此,提交 AI 生成的代码之前,必须:
- 理解主要实现。
- 检查功能正确性。
- 检查安全性。
- 验证测试。
- 删除无关修改。
- 补充必要文档。
维护者最终接受的是长期维护责任,而不是一次性的代码输出。
第 9 章 Code Review:代码审查
9.1 为什么需要 Code Review?
Code Review 不仅仅是寻找错误。
它还有以下价值:
- 提高代码质量。
- 发现设计缺陷。
- 传播项目知识。
- 统一开发规范。
- 帮助初级工程师学习。
- 减少错误进入生产环境的概率。
即使你不是高级工程师,也可以参与 Review。
新成员有时反而更容易发现项目中的隐含假设。
9.2 Code Review 的六项原则
原则一:Review the Code, Not the Person
不要针对个人。
不好的评论:
You wrote confusing code.
更好的评论:
This function is difficult to follow.
Could we separate validation and processing?
原则二:Prefer Actionable Comments
评论应该让作者知道下一步怎么做。
不好的评论:
Don't use globals.
更好的评论:
Could you replace these global variables
with a configuration dataclass?
This would allow tests to run independently
and safely in parallel.
原则三:Ask Questions Rather Than Making Demands
例如:
What happens if this value is null?
比直接命令:
Handle null values.
更容易展开有效讨论。
原则四:Explain the Why
建议:
Consider using a named constant here
so the timeout can be adjusted by environment.
而不是仅仅说:
Use a constant.
原则五:Distinguish Blocking Issues and Suggestions
可以在评论中区分:
- Blocking:必须修改的问题。
- Suggestion:改进建议。
- Nit:非阻塞的小问题。
原则六:Acknowledge Good Work
不要只指出问题。
如果某个实现很好,也应该告诉作者原因。
代码审查应该帮助团队建立更好的工程习惯,而不是让作者感到所有修改都在被否定。
9.3 Know When to Stop
不要把每个细节都变成必须修改的要求。
优先处理:
- 正确性。
- 安全性。
- 兼容性。
- 可维护性。
- 重要的性能问题。
对于不影响整体质量的小型风格问题,应合理控制评论数量。
第 10 章 Education:如何提出有效的技术问题
程序员需要持续学习,也需要向其他人提问。
课程介绍了五个重要方法。
1. State Your Understanding First
先说明自己已经理解的内容。
例如:
我的理解是 LEFT JOIN 会保留左表的所有行,
即使右表没有匹配记录也会保留。
这个理解正确吗?
2. Ask Yes/No Questions
适当提出可以用是或否回答的问题。
这样更容易确认某个具体理解是否正确,避免无关讨论。
3. Be Specific
不要问:
How does SQL work?
可以问:
LEFT JOIN 是否会保留右表中没有匹配记录的左表行?
4. Admit When You Don't Understand
如果不理解一个概念,应直接说明。
我理解了前面的执行流程,
但不清楚这里为什么需要使用事务隔离级别。
这比假装理解更有助于学习。
5. Don't Accept Incomplete Answers
不要因为别人给出一个看起来专业的答案就停止思考。
应该继续追问,直到真正理解。
当然,也要尊重对方时间。
这些原则同样适用于与 LLM 对话。
第 11 章 AI Etiquette:AI 使用规范
AI 已经成为软件开发的重要工具,但使用方式仍然需要遵守工程伦理和团队规则。
11.1 Disclose AI Usage
当 AI 对工作产生实质性贡献时,应该按照团队和项目要求披露。
例如:
AI Assistance:
- AI helped generate the initial unit tests.
- The implementation was manually reviewed.
- All tests were executed by the contributor.
比简单写一句“Used AI”更有价值。
11.2 Follow Team Policies
不同团队可能对以下问题有不同要求:
- 哪些代码可以发送到云端模型?
- 是否允许使用第三方 AI 服务?
- 是否可以让 AI 生成核心业务代码?
- 是否需要记录 AI 参与情况?
- 是否涉及数据驻留和合规要求?
应该遵守组织的规则。
11.3 Interviews and Assessments
面试和考试通常是为了评估个人能力。
如果不确定是否允许使用 AI,应该事先询问。
不能假设所有考核都允许外部 AI 工具。
第三部分:Code Quality(代码质量)
第 12 章 代码质量体系概述
代码能够运行,并不代表代码质量足够好。
例如:
def process(data):
result = []
for x in data:
if x > 0:
if x < 100:
result.append(x)
return result
它可能运行正常,但仍然存在:
- 风格不统一。
- 条件嵌套不必要。
- 缺少类型注解。
- 缺少测试。
- 没有错误处理。
- 没有说明输入约束。
代码质量需要多种工具共同保障。
本课程介绍六项主要内容:
- Formatting
- Linting
- Testing
- Pre-commit Hooks
- Continuous Integration
- Command Runners
另外还介绍 Regular Expressions。
第 13 章 Formatting:自动格式化
13.1 什么是代码格式化?
Formatter 会自动调整代码的表面形式。
例如:
原始代码:
def calculate(a,b):
return a+b
格式化后:
def calculate(a, b):
return a + b
主要处理:
- 缩进。
- 空格。
- 引号。
- 换行。
- 行长度。
- 代码布局。
13.2 为什么需要统一格式?
如果每个人都按照自己的习惯编写代码,团队会在大量无关紧要的风格问题上浪费时间。
这类争论在软件工程中称为 Bike-shedding。
例如:
- 使用单引号还是双引号?
- 缩进使用两个空格还是四个空格?
- 一行代码最长多少字符?
如果 Formatter 能够自动统一这些选择,开发者就能将注意力放到逻辑和设计上。
13.3 常见工具
| 工具 |
语言 |
| Ruff Formatter |
Python |
| Black |
Python |
| Prettier |
JavaScript、TypeScript 等 |
| gofmt |
Go |
Python 项目可以执行:
ruff format .
如果只想检查、不修改:
ruff format --check .
13.4 Formatter 配置
一些工具支持较多配置。
建议将项目格式配置提交到版本控制中。
此外,还可以使用 EditorConfig。
例如:
root = true
<li>charset = utf-8</li>
end_of_line = lf
insert_final_newline = true
[*.py]
indent_style = space
indent_size = 4
它能够帮助不同 IDE 使用一致的编辑器设置。
第 14 章 Linting:静态代码分析
14.1 什么是 Linter?
Linter 在不运行程序的情况下分析代码,寻找可疑模式和潜在问题。
这叫 Static Analysis(静态分析)。
例如:
import os
def calculate():
x = 10
return 42
这里存在:
Linter 可以发现这些问题。
14.2 Formatter 与 Linter 的区别
| 对比 |
Formatter |
Linter |
| 目标 |
统一外观 |
发现问题 |
| 关注 |
表面语法 |
代码模式和潜在错误 |
| 是否修改代码 |
通常可以 |
部分规则可以 |
| 示例 |
Ruff Format |
Ruff Check |
14.3 使用 Ruff
安装:
pip install ruff
检查:
ruff check .
自动修复可修复的问题:
ruff check --fix .
检查格式:
ruff format --check .
14.4 Linter Rules
Linter 通常包含大量规则。
某些规则可能:
- 检查未使用变量。
- 检查未使用导入。
- 检查不合理的条件嵌套。
- 检查危险函数调用。
- 检查不合理的代码复杂度。
不同规则可以根据项目情况配置。
14.5 False Positives:误报
Linter 并不完美。
有些情况下,它可能认为某种写法有问题,但开发者实际上有合理理由。
因此可以通过配置或局部注释关闭某些规则。
例如:
这类抑制应该有明确理由,不应该把它当成解决真实安全问题的默认方式。
14.6 Semgrep:基于语法结构的代码搜索
普通 grep 主要根据字符进行搜索。
Semgrep 可以基于程序语法结构匹配代码模式。
例如,课程展示了对以下危险模式的检查:
subprocess.Popen(
command,
shell=True
)
命令:
semgrep -l python \
-e "subprocess.Popen(..., shell=True, ...)"
这种方式能够比简单的文本匹配更准确地查找符合语法结构的代码。
适用场景:
- 安全规则。
- 自定义代码规范。
- 大型代码库检查。
- 危险 API 搜索。
第 15 章 Testing:自动化测试
15.1 为什么需要测试?
测试的基本思想:
编写程序之后,再编写一组程序来验证它的行为是否符合预期。
例如:
def add(a, b):
return a + b
测试:
def test_add():
assert add(2, 3) == 5
测试通过,说明在这个输入条件下,程序符合预期。
但一个测试无法证明函数在所有输入下都正确。
15.2 Unit Testing:单元测试
单元测试检查一个较小的功能单元。
Python 常用 pytest。
安装:
pip install pytest
项目结构:
project/
├── calculator.py
└── tests/
└── test_calculator.py
calculator.py:
def add(a: int, b: int) -> int:
return a + b
def divide(a: float, b: float) -> float:
if b == 0:
raise ValueError("b cannot be zero")
return a / b
test_calculator.py:
import pytest
from calculator import add, divide
def test_add():
assert add(2, 3) == 5
def test_divide():
assert divide(10, 2) == 5
def test_divide_by_zero():
with pytest.raises(ValueError):
divide(10, 0)
执行:
pytest
15.3 Integration Testing:集成测试
集成测试验证多个模块之间能否正确协作。
例如:
API
↓
Service
↓
Database
需要验证:
- API 是否正确调用 Service。
- Service 是否正确访问数据库。
- 数据是否能够正确保存和读取。
15.4 Functional Testing:功能测试
功能测试主要从用户功能或完整业务流程出发。
例如:
用户注册
↓
用户登录
↓
创建订单
↓
支付订单
↓
查询订单
测试重点是整个流程是否满足预期需求。
15.5 Test-Driven Development:测试驱动开发
TDD 的基本循环:
Red → Green → Refactor
Red
先编写测试,让它因为功能尚未实现而失败。
Green
编写最少的代码,让测试通过。
Refactor
在测试保护下改进代码结构。
这种方法能够让开发者在编写实现之前就明确预期行为。
15.6 Regression Testing:回归测试
当程序发生 Bug 时,不仅应该修复 Bug,还应该增加相应测试。
例如:
某个函数曾经在空输入下崩溃。
修复后增加:
def test_empty_input():
assert process([]) == []
以后每次修改程序时,都可以自动检查这个问题是否再次出现。
15.7 Mocking:模拟外部依赖
如果程序依赖第三方 API 或数据库,测试时不一定需要真的访问外部服务。
可以使用 Mock 替代真实依赖。
例如:
from unittest.mock import Mock
def fetch_user(client, user_id):
return client.get_user(user_id)
def test_fetch_user():
client = Mock()
client.get_user.return_value = {
"id": 1,
"name": "Alice"
}
result = fetch_user(client, 1)
assert result["name"] == "Alice"
这样可以:
- 避免真实网络请求。
- 避免依赖外部服务是否可用。
- 提高测试速度。
- 控制测试输入。
但 Mock 不应过度使用,否则测试可能只验证模拟对象,而没有验证真实系统的集成行为。
15.8 Property-Based Testing:基于性质的测试
普通单元测试通常使用手工指定的输入。
例如:
assert add(2, 3) == 5
Property-Based Testing 则通过描述程序应当满足的性质,让工具自动生成大量输入。
教材介绍了 Hypothesis。
安装:
pip install hypothesis
例如,假设我们有一个字符串填充函数:
def pad(text: str, length: int) -> str:
return text.ljust(length)
我们希望满足:
[
|\operatorname{pad}(s,n)| \geq n
]
对于任意合法的字符串 (s) 和非负整数 (n),填充后的长度不应该小于 (n)。
测试可以写成:
from hypothesis import given
from hypothesis import strategies as st
@given(
text=st.text(max_size=20),
length=st.integers(min_value=0, max_value=50)
)
def test_pad_length(text, length):
result = pad(text, length)
assert len(result) >= length
Hypothesis 会生成许多输入并检查性质。
但它不是数学证明。
它只是通过大量生成的测试样本寻找违反性质的情况。
测试数据的范围和性质仍然需要开发者合理设计。
第 16 章 Code Coverage:代码覆盖率
16.1 什么是覆盖率?
Code Coverage 衡量运行测试时有多少代码被执行。
例如:
def classify(x):
if x > 0:
return "positive"
elif x < 0:
return "negative"
return "zero"
如果只测试:
classify(10)
那么负数和零的分支就没有被执行。
覆盖率报告可以帮助开发者发现未测试区域。
16.2 使用 pytest-cov
安装:
pip install pytest-cov
执行:
pytest --cov=src --cov-report=html
生成 HTML 报告。
查看:
htmlcov/index.html
可以看到:
- 哪些文件被测试。
- 哪些代码行被执行。
- 哪些分支没有覆盖。
16.3 为什么覆盖率不等于质量?
假设:
def divide(a, b):
return a / b
测试:
def test_divide():
divide(10, 2)
这个测试可能执行了函数的全部代码行。
但它没有验证结果是否正确。
所以:
高覆盖率不一定意味着测试有效。
课程建议:
关注高质量测试,而不是单纯追求覆盖率数字。
覆盖率的真正价值是帮助发现测试盲区。
第 17 章 Pre-commit Hooks:提交前自动检查
17.1 Git Hook 的概念
Git Hook 是 Git 提供的事件触发机制。
例如,在提交前执行脚本:
git commit
↓
pre-commit hook
↓
执行检查
↓
允许或阻止提交
17.2 Pre-commit Framework
教材介绍了 Pre-commit 工具。
首先安装:
pip install pre-commit
在项目根目录创建:
.pre-commit-config.yaml
示例:
repos:
- repo: https://github.com/pre-commit/pre-commit-hooks
rev: v5.0.0
hooks:
- id: trailing-whitespace
- id: end-of-file-fixer
- repo: https://github.com/astral-sh/ruff-pre-commit
rev: v0.9.0
hooks:
- id: ruff
- id: ruff-format
注意:示例版本仅用于说明配置结构,真实项目应根据当前工具版本选择经过验证的版本。
安装 Hook:
pre-commit install
现在执行:
git commit -m "Add new feature"
Git 会在提交前执行配置的检查。
如果检查不通过,提交可能被阻止。
开发者修复问题后重新提交即可。
第 18 章 Continuous Integration:持续集成
18.1 什么是 CI?
CI 是 Continuous Integration 的缩写。
它指将代码集成到共享代码库时,自动运行构建和质量检查。
例如:
开发者修改代码
↓
git push
↓
GitHub Actions
↓
自动运行检查
↓
返回检查状态
CI 能够在代码进入主分支之前发现问题。
18.2 GitHub Actions
在项目中创建:
.github/workflows/ci.yml
示例:
name: Python CI
on:
push:
pull_request:
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: "3.12"
- name: Install dependencies
run: |
python -m pip install pytest ruff
- name: Check formatting
run: ruff format --check .
- name: Lint
run: ruff check .
- name: Test
run: pytest
当代码 Push 或 PR 时,GitHub Actions 会自动运行。
18.3 为什么 CI 使用 Check-only Mode?
在开发者本地:
ruff format .
可以自动修改代码。
但是在 CI 中,通常使用:
ruff format --check .
原因是 CI 的任务应该是验证提交的代码,而不是悄悄修改代码。
如果格式不正确,就返回失败,让开发者修复后重新提交。
18.4 Matrix Testing:矩阵测试
有些项目需要同时支持:
还可能支持:
- Python 3.11
- Python 3.12
- Python 3.13
可以通过 CI Matrix 让多个环境自动执行相同测试。
这样能发现本地开发环境中不容易暴露的兼容性问题。
18.5 Scheduled CI:定期检查
CI 不一定只在代码变化时运行。
也可以设置定时任务。
例如,每周重新检查依赖。
为什么?
因为即使你的代码没有变化,外部依赖也可能发布新版本,或者出现兼容性和安全问题。
定期 CI 可以帮助发现这些问题。
18.6 CI Status Badge
GitHub README 中经常出现:
Build: Passing
这类状态标记可以告诉使用者最近的自动化检查是否通过。
但它只能表示指定工作流的状态,不代表软件在所有环境中都没有问题。
第 19 章 Continuous Deployment:持续部署
CI 主要验证代码。
CD 则进一步将通过验证的修改部署到目标环境。
例如:
git push
↓
CI 检查
↓
构建网站
↓
部署到 GitHub Pages
教材以 Missing Semester 网站为例,说明代码更新后可以自动构建并发布网站。
CD 也可以用于:
- 发布 Docker 镜像。
- 部署 Web 服务。
- 发布二进制文件。
- 更新文档网站。
CI 和 CD 可以结合在同一个自动化流水线中。
第 20 章 Command Runners:项目命令管理
随着项目规模扩大,命令可能越来越复杂。
例如:
uv run ruff check .
uv run ruff format .
uv run pytest
uv run mypy .
Command Runner 可以将这些命令封装为简短入口。
课程介绍了 just。
例如创建:
lint:
uv run ruff check .
format:
uv run ruff format .
test:
uv run pytest
typecheck:
uv run mypy .
然后执行:
just lint
just format
just test
just typecheck
这样新加入项目的开发者不需要记住所有工具的完整参数。
类似能力也可以由:
- npm scripts
- Hatch scripts
- Make
- 其他项目管理工具
提供。
第 21 章 Regular Expressions:正则表达式
21.1 什么是正则表达式?
Regular Expression(Regex)是一种描述字符串集合和匹配模式的语言。
例如:
abc
匹配字符串中的 abc。
\d+
匹配一个或多个数字。
missing|semester
匹配 missing 或 semester。
正则表达式常用于:
- 文本搜索。
- 日志分析。
- 数据验证。
- 批量替换。
- 命令行工具。
- IDE 搜索。
- 测试筛选。
21.2 基础语法
| 表达式 |
含义 |
abc |
字面匹配 abc |
. |
任意单个字符(默认不匹配换行符) |
[abc] |
a、b、c 中的一个 |
[^abc] |
不属于 a、b、c 的字符 |
[a-f] |
a 到 f 范围中的字符 |
a|b |
匹配 a 或 b |
\d |
数字字符 |
\w |
单词字符 |
\b |
单词边界 |
(...) |
分组 |
? |
前面的模式出现零次或一次 |
* |
前面的模式出现零次或多次 |
+ |
前面的模式出现一次或多次 |
{N} |
前面的模式重复 N 次 |
\. |
匹配真正的点号 |
\\ |
匹配真正的反斜杠 |
^ |
行或字符串开头 |
$ |
行或字符串结尾 |
21.3 日期匹配
\d{4}-\d{2}-\d{2}
匹配:
2026-01-14
但不验证日期是否合法。
例如:
2026-01-99
仍然能够匹配。
21.4 邮箱匹配
教材给出了简单示例:
.+@.+
它只表示:
- @ 前面至少有一个字符。
- @ 后面至少有一个字符。
这不是可靠的邮箱验证规则。
完整邮箱地址验证涉及更多语法和规范,通常应使用成熟的验证方案,而不是自己编写一个极其复杂的正则表达式。
21.5 Capture Groups:捕获组
例如:
import re
text = "2026-01-14"
match = re.match(
r"\d{4}-(\d{2})-\d{2}",
text
)
print(match.group(1))
输出:
01
括号:
(\d{2})
表示捕获一组两位数字。
21.6 Greedy and Non-greedy:贪婪与非贪婪
例如:
".*"
* 默认采用贪婪匹配,尽可能匹配更多内容。
而:
".*?"
使用非贪婪匹配,尽可能匹配较短内容。
这在文本提取中非常重要。
21.7 Regex 的局限性
正则表达式非常适合简单文本模式。
但不适合所有结构化数据解析。
例如:
- HTML。
- 嵌套 JSON。
- 复杂编程语言语法。
- 有任意层级嵌套结构的数据。
对于 JSON,应该使用 JSON Parser:
import json
data = '''
{
"name": "Alyssa P. Hacker",
"college": "MIT"
}
'''
obj = json.loads(data)
print(obj["name"])
对于复杂语法结构,应使用专门的 Parser。
选择工具的原则:简单文本模式使用 Regex,结构化数据使用对应解析器。
第四部分:综合实践项目
第 22 章 建立完整的软件工程工作流
现在将三个主题整合起来。
项目:Markdown Link Extractor。
22.1 项目需求
实现一个 Python 命令行程序:
link-extractor input.md
提取 Markdown 文件中的链接。
支持:
link-extractor input.md --output links.txt
将提取结果写入文件。
要求:
- 使用类型注解。
- 使用 argparse。
- 有合理的异常处理。
- 编写单元测试。
- 使用 Ruff。
- 使用 mypy。
- 配置 Pre-commit。
- 配置 GitHub Actions。
- 编写 README。
- 通过 Pull Request 完成代码审查。
22.2 创建项目
mkdir markdown-link-extractor
cd markdown-link-extractor
git init -b main
uv init --package
创建虚拟环境并安装开发工具:
uv add --dev pytest ruff mypy pre-commit
22.3 让 Coding Agent 实现功能
给 Agent 提供:
请在当前项目中实现 Markdown Link Extractor。
功能:
1. 接收 Markdown 文件路径。
2. 提取普通 Markdown 链接。
3. 支持 --output 指定输出文件。
4. 输入文件不存在时返回清晰错误。
5. 使用类型注解。
6. 为主要功能编写单元测试。
限制:
1. 不修改输入文件。
2. 优先使用 Python 标准库。
3. 不要为了通过测试而删除测试。
4. 不要关闭 Linter 规则来隐藏问题。
完成后:
运行 pytest、ruff 和 mypy,
并报告实际结果。
22.4 编写测试
至少测试:
- 有一个链接。
- 有多个链接。
- 没有链接。
- 空文件。
- 非法文件路径。
- 输出到指定文件。
例如:
def test_extract_single_link():
text = "[Google](https://google.com)"
assert extract(text) == [
"https://google.com"
]
def test_extract_no_link():
text = "No links here"
assert extract(text) == []
这里的测试针对简单 Markdown 链接格式,不代表完整覆盖所有 Markdown 语法。
22.5 配置质量检查
执行:
uv run ruff format .
uv run ruff check .
uv run mypy src/
uv run pytest
确保所有检查通过。
22.6 配置 Pre-commit
添加 .pre-commit-config.yaml,让提交前自动执行格式和 Lint 检查。
安装:
uv run pre-commit install
22.7 配置 CI
创建:
.github/workflows/ci.yml
在每次 Push 和 PR 时运行:
- Ruff Format Check。
- Ruff Lint。
- Mypy。
- Pytest。
22.8 编写 README
README 至少应该包括:
# Markdown Link Extractor
## What
A command-line tool for extracting links
from Markdown documents.
## Why
It helps inspect and process links
without manually reading the document.
## Usage
link-extractor input.md
## Installation
...
## Development
...
## Testing
...
22.9 提交 Git Commit
git add -p
git commit -m "Add Markdown link extraction CLI"
复杂修改应该拆分为多个逻辑独立的 Commit。
22.10 创建 Pull Request
PR 应当说明:
- 解决了什么问题。
- 实现了什么功能。
- 为什么使用当前方案。
- 如何验证。
- 有哪些限制。
最后让其他开发者进行 Code Review。
第五部分:课程练习与考核
第 23 章 分阶段实践任务
建议不要一次完成所有练习,而是分阶段训练。
阶段一:Coding Agent
| 任务 |
验收标准 |
| 使用 Agent 阅读陌生代码库 |
能解释项目主要模块 |
| 使用 Agent 开发小功能 |
修改符合需求 |
| 使用 Agent 修复测试失败 |
有真实测试结果 |
| 创建 AGENTS.md |
Agent 能遵守项目规则 |
| 创建 Skill |
能复用专门工作流程 |
| 创建 Subagent |
能完成独立检查任务 |
| 体验并行 Agent |
能避免工作目录冲突 |
阶段二:Beyond the Code
| 任务 |
验收标准 |
| 阅读大型项目 README |
能评价其信息组织 |
| 编写代码注释 |
解释关键设计原因 |
| 编写 Commit Message |
包含问题与解决动机 |
| 创建 Bug Report |
具有明确复现步骤 |
| 制作最小复现示例 |
能独立重现错误 |
| 创建 Pull Request |
修改范围清晰 |
| 进行 Code Review |
评论具体、可执行 |
阶段三:Code Quality
| 任务 |
验收标准 |
| 配置 Formatter |
代码风格统一 |
| 配置 Linter |
能识别常见问题 |
| 配置 Type Checker |
类型错误能够被发现 |
| 编写 Unit Tests |
核心函数得到测试 |
| 使用 Coverage |
能发现未覆盖代码 |
| 配置 Pre-commit |
提交前自动检查 |
| 配置 CI |
Push 和 PR 自动测试 |
| 学习 Regex |
能完成常见文本提取任务 |
第 24 章 最终知识框架
三部分内容可以归纳为以下知识体系。
| 领域 |
核心概念 |
核心工具或方法 |
| AI Development |
LLM、Agent Loop、Harness |
Coding Agents |
| Agent Context |
Context Window、Compaction |
AGENTS.md、Skills |
| Agent Architecture |
Tool Calling、Subagents |
MCP、Git Worktree |
| Technical Writing |
Comments、README |
技术文档 |
| Version History |
Atomic Commits |
Git Commit Message |
| Collaboration |
Issue、PR |
GitHub |
| Code Review |
Blocking、Suggestions |
Review Practices |
| Formatting |
代码风格 |
Ruff、Black、Prettier |
| Static Analysis |
静态检查 |
Ruff、Semgrep |
| Type Safety |
类型一致性 |
mypy |
| Testing |
Unit、Integration、Functional |
pytest |
| Property Testing |
性质验证 |
Hypothesis |
| Coverage |
执行覆盖情况 |
pytest-cov |
| Automation |
Pre-commit |
Git Hooks |
| Integration |
CI |
GitHub Actions |
| Deployment |
CD |
自动化部署 |
| Command Management |
命令封装 |
just |
| Text Processing |
正则表达式 |
Python re、grep |
结语:真正的软件工程能力是什么?
这三份课程材料传达了一个共同的思想:
软件工程不仅仅是写代码。
一个成熟的工程师需要同时具备以下能力:
- 开发能力:能够将需求转化为可运行的程序。
- 工具能力:能够利用 AI、Shell、Git 和自动化工具提高效率。
- 验证能力:能够使用测试、静态分析和 CI 验证程序质量。
- 表达能力:能够通过注释、文档和提交记录解释设计决策。
- 协作能力:能够参与 Issue、PR 和 Code Review。
- 责任能力:能够对代码的正确性、安全性和长期维护负责。
尤其在 AI 编程时代,生成代码的成本正在降低,但理解代码、验证代码、判断设计取舍以及维护系统的能力依然重要。
最终的学习目标不是成为一个只会向 AI 提问的人,而是成为一个能够利用 AI、工程工具和团队协作机制,持续交付可靠软件的工程师。