1
月
在社区成长 1 月
LEVEL 1
1 XP
一、背景：为什么 AI 补全很快，项目落地却经常返工
AI 编程 IDE 的价值不只是“多写几行代码”，而是帮助开发者完成需求拆解、代码检索、局部修改、测试生成、错误定位和重构验证。不过在真实工程中，模型并不了解团队约定，也不会自动掌握全部运行环境。如果直接让它“实现整个功能”，常见结果包括：调用不存在的接口、忽略异常路径、修改范围过大、测试只覆盖正常流程，甚至把令牌、日志样本等敏感内容带入上下文。
因此，更可靠的使用方式是建立一条可验证的闭环：先约束上下文，再生成计划；先做小范围修改，再通过静态检查、测试和调试验证；最后审查差异并决定是否提交。下面以 VS Code、Cursor 等具备代码补全或对话能力的 IDE 为例，使用一个本地 Python 项目演示。不同产品的菜单名称可能不同，但方法基本通用。
二、核心原理：AI IDE 实际依赖哪些信息
AI IDE 生成代码时，主要依据当前文件、光标附近代码、显式选中的文件、项目索引、对话历史以及开发者提供的规则。这里有三个关键点：
1. 上下文不是越多越好。无关文件会稀释真正重要的约束，也可能增加敏感信息暴露风险。
2. AI 输出是候选修改，不是可信结论。任何生成代码都应接受与人工代码相同的审查、测试和安全检查。
3. 可验证任务优于模糊任务。“实现日志解析”过于宽泛；“只修改 parser.py，使其拒绝超过 4096 字符的输入，并补充边界测试”更容易得到稳定结果。
三、前置条件
建议准备以下环境：
1. Python 3.11 或更高版本。
2. Git，用于创建分支和检查差异。
3. 支持 AI 补全或项目对话的 IDE。
4. pytest、ruff、mypy，用于测试、格式与类型检查。
5. 一个本地实验项目。涉及日志、恶意样本或安全测试时，仅使用自建数据、授权靶场和隔离环境，不把真实用户数据提交给外部服务。
初始化示例：
mkdir ai-ide-workflow
cd ai-ide-workflow
git init
python -m venv .venv
Windows PowerShell 激活环境：
.venv\Scripts\Activate.ps1
Linux 或 macOS：
source .venv/bin/activate
安装工具：
python -m pip install pytest ruff mypy
mkdir src tests
四、第一步：先建立项目级规则，而不是立即提问
在仓库根目录创建 PROJECT_RULES.md，写入能够被人和 AI 同时理解的约束：
项目使用 Python 3.11。
所有公开函数必须有类型标注。
业务代码放在 src，测试放在 tests。
不得新增网络请求和运行外部命令的逻辑。
解析失败应返回明确异常，不得静默忽略。
单次修改尽量限制在三个文件以内。
完成后必须运行 pytest、ruff 和 mypy。
不得把密钥、真实日志、客户数据加入提示词或测试夹具。
如果 IDE 支持专用规则文件，可以把相同内容放入其项目规则中；如果不支持，就在每次新对话开始时引用该文件。规则要短、具体、可检查。不要写“代码要优雅”这种无法验收的要求，应改为“函数不超过单一职责范围，新增逻辑必须有测试”。
五、第二步：把需求拆成可验证的小任务
假设我们需要实现一个本地安全日志解析器，输入格式如下：
2025-03-08T10:15:00Z|WARN|login_failed
不要直接要求 AI “写一个安全平台”。可以先让它只输出计划：
“阅读 PROJECT_RULES.md。目标是在 src/parser.py 中解析以竖线分隔的三字段日志。暂时不要修改代码，请列出输入约束、异常情况、拟修改文件和测试清单。禁止网络访问和外部命令执行。”
检查计划是否覆盖：字段数量、时间格式、允许的级别、空字段、超长输入以及控制字符。确认后再要求实施第一步。计划阶段可以及时发现 AI 对需求的误解，修改计划的成本远低于回滚大段代码。
六、第三步：先写接口和失败测试，再补实现
可以手工创建测试，也可以让 IDE 生成初稿后逐条审查。tests/test_parser.py 示例：
import pytest
from src.parser import LogRecord, parse_line
def test_parse_valid_line() -> None:
result = parse_line("2025-03-08T10:15:00Z|WARN|login_failed")
assert result == LogRecord(
timestamp="2025-03-08T10:15:00Z",
level="WARN",
event="login_failed",
)
def test_reject_unknown_level() -> None:
with pytest.raises(ValueError, match="level"):
parse_line("2025-03-08T10:15:00Z|ROOT|login_failed")
def test_reject_extra_field() -> None:
with pytest.raises(ValueError, match="fields"):
parse_line("2025-03-08T10:15:00Z|WARN|a|b")
def test_reject_oversized_input() -> None:
with pytest.raises(ValueError, match="long"):
parse_line("A" * 4097)
先运行测试并确认它因缺少实现而失败：
python -m pytest -q
随后让 AI 只实现满足这些测试的最小代码，并明确“不要顺便重构其他文件”。一个便于审查的实现可以是：
from dataclasses import dataclass
from datetime import datetime
@dataclass(frozen=True)
class LogRecord:
timestamp: str
level: str
event: str
def parse_line(line: str) -> LogRecord:
if len(line) > 4096:
raise ValueError("line is too long")
if "\n" in line or "\r" in line:
raise ValueError("control characters are not allowed")
fields = line.split("|")
if len(fields) != 3:
raise ValueError("expected exactly three fields")
timestamp, level, event = fields
if not all(fields):
raise ValueError("fields must not be empty")
if level not in {"INFO", "WARN", "ERROR"}:
raise ValueError("unsupported level")
try:
datetime.fromisoformat(timestamp.replace("Z", "+00:00"))
except ValueError as exc:
raise ValueError("invalid timestamp") from exc
return LogRecord(timestamp=timestamp, level=level, event=event)
这里限制长度和控制字符不是为了假设某种具体攻击，而是减少异常输入对本地日志处理流程的影响。安全需求应由实际威胁模型决定，不能仅因为 AI 建议就盲目增加复杂逻辑。
七、第四步：用静态检查约束补全结果
依次运行：
python -m ruff check src tests
python -m ruff format --check src tests
python -m mypy src
python -m pytest -q
如果某一步失败，不要把整个终端输出和整个仓库一次性丢给 AI。应提供最小信息：失败命令、完整错误栈、相关函数以及预期行为。例如：
“mypy 报告 parse_line 的异常分支类型不明确。只分析 src/parser.py 第 20 到 35 行，解释根因并给出最小补丁，不要修改测试。”
这种提示可以降低无关重构概率。若 AI 给出多个方案，应优先选择容易测试、依赖更少、符合现有项目风格的方案，而不是代码量最大的方案。
八、第五步：将 AI 用于调试，而不是让它猜答案
遇到运行时问题时，先通过断点收集事实。在 parse_line 的字段拆分后设置断点，观察 line、fields 和 level。对边界输入执行单个测试：
python -m pytest tests/test_parser.py::test_reject_extra_field -vv
调试时可让 AI 协助回答三个问题：实际值是什么、预期值是什么、两者在哪一步首次分离。不要只问“为什么不工作”。更有效的提问示例是：
“测试预期四字段输入抛出包含 fields 的 ValueError。断点显示 fields 长度为 4，但代码先校验了末尾字段。请根据当前执行顺序定位原因，只建议一个最小修改。”
对于死循环、资源占用和并发问题，可以让 IDE帮助添加临时诊断日志，但提交前必须删除临时代码，尤其不要记录令牌、完整请求体和个人数据。
九、第六步：通过 Git 差异控制修改边界
每完成一个小任务，立即查看：
git status --short
git diff -- src/parser.py tests/test_parser.py
git diff --check
重点审查以下内容：
1. 是否修改了需求之外的文件。
2. 是否引入新的依赖或配置。
3. 是否出现宽泛的 except Exception。
4. 是否把错误吞掉后返回默认值。
5. 测试是否真正触发了目标分支，而不是只验证函数能够运行。
6. 是否出现硬编码路径、密钥、内部域名或真实数据。
确认无误后再提交：
git add src/parser.py tests/test_parser.py PROJECT_RULES.md
git commit -m "add validated local log parser"
建议一个提交只对应一个可说明、可回滚的目标。AI 生成的批量修改尤其需要这种隔离，否则后续很难判断回归来自哪一部分。
十、提高补全质量的具体技巧
1. 在函数上方先写类型签名、输入约束和一个示例，补全通常会比只写函数名更稳定。
2. 对已有项目，先让 IDE总结模块依赖，再要求修改；不要让它凭文件名猜测架构。
3. 把大任务拆成“计划、测试、实现、审查”四轮对话，每轮只做一种工作。
4. 要求输出补丁范围，例如“只修改当前函数”，防止无关格式化污染差异。
5. 对数据库迁移、权限判断、加密、反序列化和外部命令执行保持人工复核。这些区域不能仅凭补全结果上线。
6. 当补全连续两次偏离需求，应重建对话并缩小上下文，而不是继续在错误假设上追加提示。
十一、风险与注意事项
第一，隐私风险。不要把生产密钥、真实恶意样本、未脱敏日志、客户源码或漏洞细节发送到未经组织批准的服务。可用合成数据替代真实数据，并检查 IDE 的索引、遥测和数据保留设置。
第二，依赖风险。AI 可能建议不存在、长期未维护或许可证不合适的软件包。新增依赖前应核对官方来源、版本、许可证和维护状态，并通过锁定文件固定版本。
第三，错误安全感。测试通过只表示已编写的断言通过，不代表不存在遗漏。边界条件、异常路径、权限校验和资源限制仍需人工设计。
第四，提示注入风险。仓库中的注释、文档或第三方样本可能包含诱导性文字。处理不可信仓库时，不应允许 IDE 自动执行其建议命令；所有脚本先阅读，再在低权限、隔离的本地环境运行。
第五，授权边界。分析可疑代码、扩展插件或日志时，应限于自有文件、明确授权样本和本地实验环境。不要将本文流程用于访问、测试或修改未授权系统。
十二、常见问题
问：应该一次把整个仓库加入上下文吗？
答：通常不应该。先提供规则文件、入口模块、相关接口和测试。只有出现跨模块依赖问题时，再逐步加入直接关联文件。
问：AI 生成的测试很多，为什么仍然会漏掉缺陷？
答：生成测试往往沿用实现中的假设，可能出现“实现错、测试也按同样方式错”的情况。应先由开发者定义关键不变量，例如字段数量必须准确、未知级别必须拒绝，再让 AI 补充组合用例。
问：补全和对话式修改如何选择？
答：局部样板代码、类型标注和重复分支适合补全；跨文件任务、错误分析和重构计划更适合对话。无论哪种方式，都要通过差异审查和自动化检查收口。
问：AI 总喜欢大范围重构怎么办？
答：在提示中限定文件、函数、禁止事项和验收命令；先要求它解释修改计划。若计划超出范围，先纠正计划，不要让它直接生成代码。
问：能否让 IDE 自动运行所有命令？
答：低风险的测试和格式检查可以在确认配置后自动化，但安装脚本、数据库迁移、删除操作、网络请求以及来源不明的仓库命令应保持人工确认。
十三、总结
高质量的 AI 编程工作流不是“提示一次，接受全部”，而是把 AI 放进现有工程纪律中：使用项目规则限制行为，用小任务控制范围，用失败测试描述需求，用静态检查发现低级错误，用断点和错误栈提供事实，再通过 Git 差异完成最终审查。这样既能获得补全和代码检索带来的效率，也能保留可追踪、可验证、可回滚的工程属性。真正值得追求的不是生成代码数量，而是在明确授权、保护数据和控制风险的前提下，更快地产出能够被测试和维护的代码。
AI 编程 IDE 的价值不只是“多写几行代码”，而是帮助开发者完成需求拆解、代码检索、局部修改、测试生成、错误定位和重构验证。不过在真实工程中，模型并不了解团队约定，也不会自动掌握全部运行环境。如果直接让它“实现整个功能”，常见结果包括：调用不存在的接口、忽略异常路径、修改范围过大、测试只覆盖正常流程，甚至把令牌、日志样本等敏感内容带入上下文。
因此，更可靠的使用方式是建立一条可验证的闭环：先约束上下文，再生成计划；先做小范围修改，再通过静态检查、测试和调试验证；最后审查差异并决定是否提交。下面以 VS Code、Cursor 等具备代码补全或对话能力的 IDE 为例，使用一个本地 Python 项目演示。不同产品的菜单名称可能不同，但方法基本通用。
二、核心原理：AI IDE 实际依赖哪些信息
AI IDE 生成代码时，主要依据当前文件、光标附近代码、显式选中的文件、项目索引、对话历史以及开发者提供的规则。这里有三个关键点：
1. 上下文不是越多越好。无关文件会稀释真正重要的约束，也可能增加敏感信息暴露风险。
2. AI 输出是候选修改，不是可信结论。任何生成代码都应接受与人工代码相同的审查、测试和安全检查。
3. 可验证任务优于模糊任务。“实现日志解析”过于宽泛；“只修改 parser.py，使其拒绝超过 4096 字符的输入，并补充边界测试”更容易得到稳定结果。
三、前置条件
建议准备以下环境：
1. Python 3.11 或更高版本。
2. Git，用于创建分支和检查差异。
3. 支持 AI 补全或项目对话的 IDE。
4. pytest、ruff、mypy，用于测试、格式与类型检查。
5. 一个本地实验项目。涉及日志、恶意样本或安全测试时，仅使用自建数据、授权靶场和隔离环境，不把真实用户数据提交给外部服务。
初始化示例：
mkdir ai-ide-workflow
cd ai-ide-workflow
git init
python -m venv .venv
Windows PowerShell 激活环境：
.venv\Scripts\Activate.ps1
Linux 或 macOS：
source .venv/bin/activate
安装工具：
python -m pip install pytest ruff mypy
mkdir src tests
四、第一步：先建立项目级规则，而不是立即提问
在仓库根目录创建 PROJECT_RULES.md，写入能够被人和 AI 同时理解的约束：
项目使用 Python 3.11。
所有公开函数必须有类型标注。
业务代码放在 src，测试放在 tests。
不得新增网络请求和运行外部命令的逻辑。
解析失败应返回明确异常，不得静默忽略。
单次修改尽量限制在三个文件以内。
完成后必须运行 pytest、ruff 和 mypy。
不得把密钥、真实日志、客户数据加入提示词或测试夹具。
如果 IDE 支持专用规则文件，可以把相同内容放入其项目规则中；如果不支持，就在每次新对话开始时引用该文件。规则要短、具体、可检查。不要写“代码要优雅”这种无法验收的要求，应改为“函数不超过单一职责范围，新增逻辑必须有测试”。
五、第二步：把需求拆成可验证的小任务
假设我们需要实现一个本地安全日志解析器，输入格式如下：
2025-03-08T10:15:00Z|WARN|login_failed
不要直接要求 AI “写一个安全平台”。可以先让它只输出计划：
“阅读 PROJECT_RULES.md。目标是在 src/parser.py 中解析以竖线分隔的三字段日志。暂时不要修改代码，请列出输入约束、异常情况、拟修改文件和测试清单。禁止网络访问和外部命令执行。”
检查计划是否覆盖：字段数量、时间格式、允许的级别、空字段、超长输入以及控制字符。确认后再要求实施第一步。计划阶段可以及时发现 AI 对需求的误解，修改计划的成本远低于回滚大段代码。
六、第三步：先写接口和失败测试，再补实现
可以手工创建测试，也可以让 IDE 生成初稿后逐条审查。tests/test_parser.py 示例：
import pytest
from src.parser import LogRecord, parse_line
def test_parse_valid_line() -> None:
result = parse_line("2025-03-08T10:15:00Z|WARN|login_failed")
assert result == LogRecord(
timestamp="2025-03-08T10:15:00Z",
level="WARN",
event="login_failed",
)
def test_reject_unknown_level() -> None:
with pytest.raises(ValueError, match="level"):
parse_line("2025-03-08T10:15:00Z|ROOT|login_failed")
def test_reject_extra_field() -> None:
with pytest.raises(ValueError, match="fields"):
parse_line("2025-03-08T10:15:00Z|WARN|a|b")
def test_reject_oversized_input() -> None:
with pytest.raises(ValueError, match="long"):
parse_line("A" * 4097)
先运行测试并确认它因缺少实现而失败：
python -m pytest -q
随后让 AI 只实现满足这些测试的最小代码，并明确“不要顺便重构其他文件”。一个便于审查的实现可以是：
from dataclasses import dataclass
from datetime import datetime
@dataclass(frozen=True)
class LogRecord:
timestamp: str
level: str
event: str
def parse_line(line: str) -> LogRecord:
if len(line) > 4096:
raise ValueError("line is too long")
if "\n" in line or "\r" in line:
raise ValueError("control characters are not allowed")
fields = line.split("|")
if len(fields) != 3:
raise ValueError("expected exactly three fields")
timestamp, level, event = fields
if not all(fields):
raise ValueError("fields must not be empty")
if level not in {"INFO", "WARN", "ERROR"}:
raise ValueError("unsupported level")
try:
datetime.fromisoformat(timestamp.replace("Z", "+00:00"))
except ValueError as exc:
raise ValueError("invalid timestamp") from exc
return LogRecord(timestamp=timestamp, level=level, event=event)
这里限制长度和控制字符不是为了假设某种具体攻击，而是减少异常输入对本地日志处理流程的影响。安全需求应由实际威胁模型决定，不能仅因为 AI 建议就盲目增加复杂逻辑。
七、第四步：用静态检查约束补全结果
依次运行：
python -m ruff check src tests
python -m ruff format --check src tests
python -m mypy src
python -m pytest -q
如果某一步失败，不要把整个终端输出和整个仓库一次性丢给 AI。应提供最小信息：失败命令、完整错误栈、相关函数以及预期行为。例如：
“mypy 报告 parse_line 的异常分支类型不明确。只分析 src/parser.py 第 20 到 35 行，解释根因并给出最小补丁，不要修改测试。”
这种提示可以降低无关重构概率。若 AI 给出多个方案，应优先选择容易测试、依赖更少、符合现有项目风格的方案，而不是代码量最大的方案。
八、第五步：将 AI 用于调试，而不是让它猜答案
遇到运行时问题时，先通过断点收集事实。在 parse_line 的字段拆分后设置断点，观察 line、fields 和 level。对边界输入执行单个测试：
python -m pytest tests/test_parser.py::test_reject_extra_field -vv
调试时可让 AI 协助回答三个问题：实际值是什么、预期值是什么、两者在哪一步首次分离。不要只问“为什么不工作”。更有效的提问示例是：
“测试预期四字段输入抛出包含 fields 的 ValueError。断点显示 fields 长度为 4，但代码先校验了末尾字段。请根据当前执行顺序定位原因，只建议一个最小修改。”
对于死循环、资源占用和并发问题，可以让 IDE帮助添加临时诊断日志，但提交前必须删除临时代码，尤其不要记录令牌、完整请求体和个人数据。
九、第六步：通过 Git 差异控制修改边界
每完成一个小任务，立即查看：
git status --short
git diff -- src/parser.py tests/test_parser.py
git diff --check
重点审查以下内容：
1. 是否修改了需求之外的文件。
2. 是否引入新的依赖或配置。
3. 是否出现宽泛的 except Exception。
4. 是否把错误吞掉后返回默认值。
5. 测试是否真正触发了目标分支，而不是只验证函数能够运行。
6. 是否出现硬编码路径、密钥、内部域名或真实数据。
确认无误后再提交：
git add src/parser.py tests/test_parser.py PROJECT_RULES.md
git commit -m "add validated local log parser"
建议一个提交只对应一个可说明、可回滚的目标。AI 生成的批量修改尤其需要这种隔离，否则后续很难判断回归来自哪一部分。
十、提高补全质量的具体技巧
1. 在函数上方先写类型签名、输入约束和一个示例，补全通常会比只写函数名更稳定。
2. 对已有项目，先让 IDE总结模块依赖，再要求修改；不要让它凭文件名猜测架构。
3. 把大任务拆成“计划、测试、实现、审查”四轮对话，每轮只做一种工作。
4. 要求输出补丁范围，例如“只修改当前函数”，防止无关格式化污染差异。
5. 对数据库迁移、权限判断、加密、反序列化和外部命令执行保持人工复核。这些区域不能仅凭补全结果上线。
6. 当补全连续两次偏离需求，应重建对话并缩小上下文，而不是继续在错误假设上追加提示。
十一、风险与注意事项
第一，隐私风险。不要把生产密钥、真实恶意样本、未脱敏日志、客户源码或漏洞细节发送到未经组织批准的服务。可用合成数据替代真实数据，并检查 IDE 的索引、遥测和数据保留设置。
第二，依赖风险。AI 可能建议不存在、长期未维护或许可证不合适的软件包。新增依赖前应核对官方来源、版本、许可证和维护状态，并通过锁定文件固定版本。
第三，错误安全感。测试通过只表示已编写的断言通过，不代表不存在遗漏。边界条件、异常路径、权限校验和资源限制仍需人工设计。
第四，提示注入风险。仓库中的注释、文档或第三方样本可能包含诱导性文字。处理不可信仓库时，不应允许 IDE 自动执行其建议命令；所有脚本先阅读，再在低权限、隔离的本地环境运行。
第五，授权边界。分析可疑代码、扩展插件或日志时，应限于自有文件、明确授权样本和本地实验环境。不要将本文流程用于访问、测试或修改未授权系统。
十二、常见问题
问：应该一次把整个仓库加入上下文吗？
答：通常不应该。先提供规则文件、入口模块、相关接口和测试。只有出现跨模块依赖问题时，再逐步加入直接关联文件。
问：AI 生成的测试很多，为什么仍然会漏掉缺陷？
答：生成测试往往沿用实现中的假设，可能出现“实现错、测试也按同样方式错”的情况。应先由开发者定义关键不变量，例如字段数量必须准确、未知级别必须拒绝，再让 AI 补充组合用例。
问：补全和对话式修改如何选择？
答：局部样板代码、类型标注和重复分支适合补全；跨文件任务、错误分析和重构计划更适合对话。无论哪种方式，都要通过差异审查和自动化检查收口。
问：AI 总喜欢大范围重构怎么办？
答：在提示中限定文件、函数、禁止事项和验收命令；先要求它解释修改计划。若计划超出范围，先纠正计划，不要让它直接生成代码。
问：能否让 IDE 自动运行所有命令？
答：低风险的测试和格式检查可以在确认配置后自动化，但安装脚本、数据库迁移、删除操作、网络请求以及来源不明的仓库命令应保持人工确认。
十三、总结
高质量的 AI 编程工作流不是“提示一次，接受全部”，而是把 AI 放进现有工程纪律中：使用项目规则限制行为，用小任务控制范围，用失败测试描述需求，用静态检查发现低级错误，用断点和错误栈提供事实，再通过 Git 差异完成最终审查。这样既能获得补全和代码检索带来的效率，也能保留可追踪、可验证、可回滚的工程属性。真正值得追求的不是生成代码数量，而是在明确授权、保护数据和控制风险的前提下，更快地产出能够被测试和维护的代码。
