📚 喵喵的笔记库

参考-RedHat-Harness-Engineering-Structured-Workflows

4分钟阅读

Harness Engineering: Structured Workflows for AI-Assisted Development (Red Hat)

来源：https://developers.redhat.com/articles/2026/04/07/harness-engineering-structured-workflows-ai-assisted-development 收录时间：2026-05-18

核心原则

Structure in, structure out. 约束越多，输出越可预测。

问题：模糊输入 → 模糊输出

直接把 Jira ticket 丢给 AI coding tool，结果不可预测：

  • 臆造文件路径
  • 发明不存在的 API
  • 修改错误的模块
  • 根本原因：AI 在猜测而不是在查看代码库

解法：两阶段工作流

Phase 1：Repository Impact Map（仓库影响图）

AI 扫描实际代码库，使用 LSP 和 MCP 检查仓库结构（查找符号、追踪引用、搜索模式），产出影响图：

trustify (backend):
  changes:
    - Add CSV serialization for SBOM query results
    - Add GET /api/v2/sbom/export endpoint

trustify-ui (frontend):
  changes:
    - Add "Export CSV" button to SBOM list toolbar

关键步骤：人类审查影响图。 如果 AI 选错了模块、漏了仓库、发明了不存在的端点模式——在这里捕获，防止后续产出"编译通过但解决错误问题"的代码。

Phase 2：Structured Task Template（结构化任务模板）

每个工作单元变成严格模板的 Jira task：

## Repository
trustify

## Description
Add a CSV export endpoint for SBOM query results.

## Files to Modify
- `modules/sbom/src/service.rs` — add CSV serialization method
- `modules/sbom/src/endpoints.rs` — add GET handler

## Implementation Notes
Follow the existing JSON export pattern in `SbomService::export_json()`.
Reuse the `QueryResult` type from `modules/sbom/src/model.rs`.

## Acceptance Criteria
- [ ] GET /api/v2/sbom/export?format=csv returns valid CSV
- [ ] Existing JSON export still works

## Test Requirements
- [ ] Integration test in `modules/sbom/tests/` following existing test patterns

每个字段都有目的：

  • Repository — 限定单一仓库，避免跨仓库混淆
  • Files to Modify — 分析阶段找到的真实路径，不是猜测
  • Implementation Notes — 引用实际符号名和现有模式，AI 可以查找函数并模仿结构
  • Acceptance Criteria — 具体检查清单
  • Test Requirements — 测试覆盖指导

迭代改进

  • 早期版本没有审查检查点 → AI 从"发现什么"直接跳到创建任务 → 加了人类审查减少了明显错误
  • 任务模板最初有通用 Notes 字段 → 改为 Implementation Notes + 要求引用实际代码符号 → 结果质量显著提升
  • 模糊描述 = 规划阶段没有基于真实分析的信号

四条 Takeaway

  1. 让 AI 先看真实代码再规划 — 基于符号分析的仓库影响图让下游任务扎根于真实代码
  2. 给 AI 结构化约束 — 文件路径、符号名、要遵循的现有模式：输入越具体，输出越一致
  3. 规划和实现之间加人类审查检查点 — 在 3 行影响图里捕获错误 < 在 PR 里捕获错误
  4. 投资 Jira feature 的质量 — 好的 feature description 直接改善 AI 的规划和代码

Next Steps

  • 让仓库成为唯一真相源——把规范、命名规则、架构决策都放进仓库（CLAUDE.md / CONVENTIONS.md）
  • 把 harness 当软件维护——Skills、prompts、MCP 配置都要版本化、PR 审查、重构
  • 关闭环反馈——当生成的计划或 PR 错误时，追溯错误到输入：缺失约束、模糊验收标准、AI 看不到的符号。修 harness，不只修输出
  • 通过 MCP 扩展 Agent 工具箱——CI 状态、部署日志、运行时指标都是真实数据源

关系图谱