12-Context与Harness工程

12-Context 与测试验证工程基于Cursor 3.0.9user setup及官方文档中的能力说明如何为 Chat / Agent 提供高质量上下文以及如何在本机用测试与终端验证 AI 产出。术语说明「Context Engineering」在业界常指「为模型精选、组织上下文」「Harness Engineering」在本文中指「测试执行与验证体系」——二者不是Cursor 产品里的单独菜单名称对应能力分散在 Context、Rules、索引、Agent、终端、Hooks 等模块中。官方文档入口Cursor Docs含 Context、Rules、Agent、Hooks 等。一、Cursor 官方语境下的「上下文」是什么1.1 目标让模型在回答或改代码时看到的是相关、可信、不过载的信息当前任务涉及的文件、规则、仓库语义检索结果、外部文档等而不是整仓无关噪声。1.2 上下文常见来源与官方能力对齐下列为 Cursor 中实际存在的机制具体名称以你安装的 3.0.9 界面为准来源作用备注 引用Context / Chat 输入框显式附加文件、文件夹、代码库片段、文档、网页等输入打开选择器类型名随版本可能调整如 Files、Folders、Code、Docs、Web、Git、Rules 等项目与用户 Rules长期约束风格、栈、禁止事项项目.cursor/rules/及历史.cursorrules用户Settings → Rules详见 Rules代码库索引Codebase Indexing对仓库做索引支持语义搜索与更大范围理解在Settings → Features → Codebase Indexing或同类入口管理大仓可配合忽略规则.cursorignore排除不必索引或不必暴露给 AI 的路径类似.gitignore思路减轻噪声与敏感面对话与 Composer 状态同一会话内的历史、已附加的上下文注意窗口变长时的「摘要 / 压缩」行为以产品为准MCP通过已配置的 MCP 工具拉取外部系统数据在Settings → MCP配置是否在输入框以形式出现取决于版本与服务器Linter / 诊断部分流程可附带当前文件的诊断信息以编辑器诊断与 Agent 能力为准不建议再使用本文旧版中的虚构配置官方文档与仓库中均不作为标准能力出现.cursor/context.jsoncontextEngineering.autoInclude等字段.cursor/harness.json统一测试 Harness 配置文件测试与覆盖率应使用语言生态自带工具如 pytest、coverageAgent/终端执行或用Agent Hooks做提交前拦截见 11-Cursor Hooks与自动化.md。1.3 引用写法与旧版更正在 Chat / Agent 输入框中通过打开上下文选择器再选具体条目。旧文档中的file/folder/symbol字面前缀多为示意实际 UI 常为Files、Folders、Code等类型。建议记法与官方拾取器一致意图推荐做法指定某个源文件→ 选Files再选路径或拖入侧栏文件指定目录→ 选Folders在仓库内按语义找实现→ 选Code或当前版本中的「代码库 / 语义搜索」类入口附加第三方库文档→ 选Docs若已配置索引/文档源联网检索→ 选Web若产品提供固定团队规范→ 选Cursor Rules/ 依赖项目 Rules不准确的旧表述示例易误导mcp filesystem read fileMCP 一般以已启用工具形式被 Agent 调用而不是在提示里手写一串伪命令。doc pandas.DataFrame应通过Docs或官方支持的文档索引方式附加而非假设任意doc语法。仍推荐的提示词结构与是否使用 无关请分析 [通过 附加的 analyzer.py] 中的 calculate_stats 并对照 [通过 附加的 test_analyzer.py] 中的用例优化异常处理。二、上下文工程实战官方能力组合2.1 精准引用策略场景重构函数❌ 上下文不足 「帮我重构这个函数」 → 模型不知道调用方与测试约定。 ✅ 结合 与说明 「请重构 Filessrc/utils.py 中的 process_data 保证与 Filessrc/api.py、Filessrc/models.py 中的用法兼容 行为以 Filestests/test_utils.py 为准。」2.2 分层提供信息由粗到细大型重构可拆成多轮每轮只加必要材料第一轮架构与约定 「栈Python FastAPI约定见 FilesREADME.md、Filespyproject.toml。」 第二轮影响面 「改动点在 Filessrc/database.py 的 Connection影响 Folderssrc/routes/。」 第三轮细节 「问题是高并发下连接池耗尽请先读 Filesdocs/database-best-practices.md 再给方案。」2.3 控制长度与噪声策略做法少而精优先 具体文件或小目录避免整仓大文件无差别塞入分轮对话先总结模块职责再进入局部修改索引与忽略用.cursorignore排除构建产物、node_modules、密钥路径等规则前置把稳定约束写进Rules减少在每条提示里重复粘贴2.4 与 Rules、索引的配合替代虚构的 context.json若你希望「默认多带测试、类型信息」等请用官方机制实现在Project Rules中写明修改某目录时必须同步更新测试、运行pytest等。开启并维护Codebase Indexing保证Code类检索有效。用.cursorignore控制索引范围。不要在仓库中依赖不存在的contextEngineeringJSON 配置。三、测试与验证工程Harness 方法论3.1 含义与 Cursor 的关系这里Harness指你选用的测试框架 运行方式 与 Agent 的衔接。Cursor不提供统一的harness.json产品配置Agent 可以通过终端运行pytest等命令Hooks可在特定生命周期执行检查参见 Agent Hooks。3.2 在 Cursor 3.0.9 中运行测试的常见方式方式说明集成终端Agent 或你手动执行pytest、npm test等VS Code 测试视图依赖对应语言的 Test 扩展如 Python快捷键以 Cursor/VS Code 键位绑定为准勿死记单一组合键任务Tasks在.vscode/tasks.json定义重复命令便于运行套件CI推送后在 GitHub Actions 等环境跑同一套命令作为最终门禁旧文档中的/test斜杠命令、固定的CtrlShiftT可能因版本、扩展、键位方案而异以当前产品为准。3.3 用 AI 生成测试的提示模板请为 Filessrc/calculator.py 中的 Calculator 类生成 pytest 测试 要求 1. 使用 fixture 构造实例 2. 覆盖正常与异常路径 3. 使用 parametrize 做多组数据 4. 边界条件单独用例 5. 风格对齐 Filestests/conftest.py若存在生成后务必在本机实际运行pytest以终端退出码与失败栈为准。3.4 TDD 式协作流程与 Agent1. 描述需求自然语言 2. 让 Agent「先写失败测试」描述期望行为 3. 再「实现代码直至测试通过」 4. 最后「补边界 / 覆盖率」或运行 coverage 报告后迭代四、上下文 测试的联合使用4.1 用失败测试驱动修复Filestests/test_api.py 中 test_create_user 失败报错 ForeignKeyViolation。 请结合 Filessrc/models.py、Filessrc/api.py 检查关系定义并修复。4.2 覆盖率驱动的迭代第一轮为 Filessrc/new_feature.py 补测试目标覆盖率 80%。 第二轮根据 coverage 报告中的未覆盖行补充场景。 第三轮在终端运行 pytest --cov... 确认达标。4.3 与 Hooks、CI 的分工层级建议Agent Hooks拦截 Agent 触发的 shell / 读文件等见官方 Hooks 文档Gitpre-commit本机git commit时的检查与 Cursor 无必然绑定CI团队共享、可审计的最终质量门禁五、综合工作流示例5.1 新功能认证模块1. ContextFilessrc/models.py、Filesdocs/architecture.md若有 2. 测试让 Agent 生成 / 扩展 tests/test_models.py、tests/test_auth.py 3. 实现Filessrc/auth.py 中 login/register/token 校验 4. 验证终端 pytest必要时集成测试描述写在提示中 5. 文档Filesdocs/api.md 与 docstring 同步更新5.2 复杂问题排查收集材料示例 - Fileslogs/production.log 或粘贴相关片段 - Filessrc/database.py 连接池配置 - Filesinfrastructure/k8s.yaml若相关 请基于以上分析 Timeout 可能原因并给出可验证的修复步骤 修复后请给出或运行高并发场景测试思路。六、最佳实践速查6.1 上下文对齐官方原则做法显式优于隐含关键文件用附上规则沉淀重复约束写入Rules少靠长提示控制索引面.cursorignore 索引设置适度单轮不要堆无关大文件6.2 测试与验证原则做法可执行以本机/CI 命令通过为准可重复pytest/npm test写进 README 或脚本与 Agent 对齐在提示中写明「运行 xxx 命令并修复直至通过」Hooks 慎用仅当需要拦截 Agent 行为时再配置见第 11 篇6.3 任务前自检☐ 是否用 附上了必要 Files/Folders/Code ☐ 稳定规范是否已在 Rules 中 ☐ 大仓是否已合理 .cursorignore ☐ 改动的验证命令是否在终端跑过 ☐ 敏感路径是否未误入索引或上下文七、下一步结合 07-Cursor独有技巧.md 复习与快捷操作。结合 11-Cursor Hooks与自动化.md 配置Agent Hooks注意与虚构onSave配置区分。