【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载导读在 Harness Engineering为编码型 AI Agent 搭建工作环境的实践中前端 UI 是最容易失控的部分Agent 倾向于在每次会话中“发明”新的视觉模式、组件变体与交互文案导致界面风格漂移、状态覆盖不全、回归难以发现。本仓库docs/pt-BR/resources/openai-advanced/repo-template/docs/FRONTEND.md正是一份面向 Agent 的前端约束文档本文以它为骨架结合仓库中repo-template的配套文档体系AGENTS.md、ARCHITECTURE.md、DESIGN.md、RELIABILITY.md、QUALITY_SCORE.md等以及projects/project-06的真实前端实现说明如何把“UI 原则 → 护栏规则 → 验证期望”固化为仓库级的可执行契约。读完本文你将掌握如何编写一份机器与人都能读懂的 FRONTEND.md、如何用设计系统参考文件约束组件行为、以及如何把可访问性与视觉回归检查纳入 Agent 的常规验证闭环。为什么 Agent 需要一份 FRONTEND.md原文档开宗明义该文件的存在是为了定义稳定的前端期望让 Agent 不会以不可预测的方式发明 UI 模式。这是 Harness 工程中“以仓库为系统记录system of record”思想在前端领域的落地——docs/pt-BR/resources/openai-advanced/repo-template/docs/FRONTEND.md与仓库根部的 AGENTS.md 明确约定AGENTS.md是路由层把 Agent 导向各领域文档而不是巨型指令仓库FRONTEND.md则被登记为“UI 约束、设计系统规则、可访问性检查”的唯一入口docs/FRONTEND.md: restrições de UI, regras do design system, verificações de acessibilidade.在长期运行的 Agent 会话中这正是 repo-template 的优化目标见AGENTS.md首段 otimizado para trabalhos de agentes de codificação de longa duração大模型上下文会滚动、记忆会衰减唯一能稳定约束行为的就是版本化的仓库文档。FRONTEND.md 的价值在于消灭“一次性变体”Agent 每次新增页面时容易随手写出一套新组件导致同一语义有多个实现让验证可预期明确“空/加载/成功/错误/重试”等关键状态必须登记验证不再是事后补救把可访问性当功能它被定义为“正常验证的一部分”而非打磨阶段的加分项。FRONTEND.md 的四大 UI 原则原文档给出了四条简洁但可操作的原则是后续所有护栏的判据清晰优先于新奇Otimize pela clareza antes da novidadeUI 的首要职责是传达状态与操作视觉花样不得以牺牲可理解性为代价交互流程可发现、可重启Mantenha os fluxos de interação detectáveis e reinicializáveis用户以及未来的 Agent应当能在任意时刻理解当前所处状态并能从头重做流程这与仓库中反复出现的“可重启restartable / reinicializável”理念一脉相承参见 RELIABILITY.md 的 Nenhum recurso está concluído se o sistema não puder reiniciar de forma limpa depois少量可复用组件优先于一次性变体Prefira um pequeno número de componentes reutilizáveis em vez de variantes únicas这是把“组合优于复制”落到 UI 上的工程原则直接对抗 Agent 最容易犯的“每页新写一套样式”的毛病可访问性检查属于常规验证Verificações de acessibilidade fazem parte da verificação normal键盘可达性、对比度、语义标签等与功能测试同等重要。五条护栏Guardrails把原则变成可检查的规则原则需要转化为 Agent 能执行的动作原文档定义了五条护栏在docs/references/中记录设计系统或组件库——把设计资产版本化供 Agent 查询登记面向用户的关键状态空、加载、成功、错误、重试——确保每个流程的状态覆盖完整不留“死亡分支”保持文案copy、键盘行为与视觉层级在各流程间一致——一致性是可发现性的前提修复 UI 缺陷时必须同步新增或更新对应的验证步骤——防止同一类 bug 反复出现隐含于整体证据链要求见下文的验证期望一节。这些护栏在repo-template的目录结构中都有落点docs/references/design-system-reference-llms.txt就是第 1 条护栏的具体产物。该文件说明其目标是“存储与设计系统相关的、对模型友好LLM-friendly的参考材料”并建议包含四类内容组件命名规则regras de nomenclatura de componentes间距与排版 tokentokens de espaçamento e tipografia状态变体variantes de estado可访问性期望expectativas de acessibilidade并明确“保持简洁每当主设计系统变更时更新该文件”——这正是把“护栏 1”变成 Agent 可检索、可引用的静态资产。从模板到真实实现project-06 中的状态覆盖护栏 2登记关键状态不是空话。在 projects/project-06/solution/src/renderer/components/StatusBar.tsx 中可以看到一个完整实现AppStatus的indexStatus被映射为idle / indexing / ready / error四态每种状态都有专属颜色灰色#888、琥珀#f0ad4e、绿色#5cb85c、红色#d9534f与文案Not indexed / Indexing... / Ready / Error并同步展示Documents数量、Indexed数量与Last activity时间戳。这就是“空/加载/成功/错误”四态在前端状态栏的落地用户在任何时刻都能一眼判断索引流程处于哪个阶段。再如 projects/project-06/solution/src/renderer/components/DocumentList.tsx文档列表对“空状态”做了显式处理documents.length 0时渲染No documents imported yet. / Import documents to get started.的引导文案单个文档行则根据doc.statusindexed/indexing显示Indexed或Indexing...标签并附带文件大小与 chunk 数——同一组件内状态不同但结构一致正是“少量可复用组件 状态变体”原则的示范。这两处代码说明FRONTEND.md 的护栏并不要求前端框架必须复杂而是要求状态可枚举、表现可预测、文案可发现。验证期望证据是 UI 完成的唯一凭证原文档的第三节“Expectativas de Verificação”给出了三条要求本质是把“Definition of Done”延伸到 UI 领域为关键用户旅程jornadas críticas采集证据在相关计划plano中登记浏览器或 runtime 的验证步骤若视觉回归频繁发生则标准化截图或 DOM 检查。这与 AGENTS.md 的“工作契约”完全咬合Não marque o trabalho como concluído apenas pela inspeção do código; evidências executáveis são obrigatórias仅凭代码审查不能判定完成可执行证据是强制的。也就是说一个 UI 改动只有在“实现了行为 执行了验证 证据链接到计划或质量文档”后才算完成。而RELIABILITY.md的“Golden Journeys”概念[jornada 1]…每条关键旅程都要有可重复的验证路径与明确的失败信号为“采集证据”提供了对象清单先定义哪些用户旅程是关键的再为它们设计验证。接入仓库文档体系FRONTEND.md 在 system-of-record 中的位置FRONTEND.md 不是孤立文件它嵌入在 repo-template 的一整套“以仓库为记录”的文档体系中AGENTS.md 的“路由图Mapa de Roteamento”给出了完整上下文文档职责ARCHITECTURE.md系统地图、分层模型Tipos - Configuração - Repositório - Serviço - Runtime - UI、依赖规则docs/design-docs/index.md已接受/提议/废弃的设计决策docs/product-specs/index.md当前产品行为与验收目标docs/PLANS.md计划生命周期与执行计划策略docs/QUALITY_SCORE.md领域与层级的健康度追踪docs/RELIABILITY.mdruntime 信号、基准、重启期望docs/SECURITY.md密钥、沙箱、数据与外部动作规则docs/FRONTEND.mdUI 约束、设计系统规则、可访问性检查与前端直接相关的协作点有两个与 DESIGN.md 的分工DESIGN.md 记录“持久的、跨会话的产品与系统设计决策”即为什么这样设计FRONTEND.md 则回答UI 必须长什么样、必须怎么验证。当设计规则变得“运营级关键operationally critical”时DESIGN.md 要求将其提升为自动化检查或更新 ARCHITECTURE.md——同理UI 护栏如对比度、键盘可达性达到关键级别时也应固化为 lint 规则或自动化 DOM/截图测试而不是靠每次会话口头重申。与架构层的呼应ARCHITECTURE.md 规定分层方向Tipos - Configuração - Repositório - Serviço - Runtime - UI且“UI 不得绕过 runtime 或 service 契约”。这意味着 FRONTEND.md 约束的是表现层但状态数据必须来自下层契约例如shared/types.ts中定义的AppStatus、Document类型Agent 不得为了视觉便利而绕开服务层直接拼接数据——这从架构上保证了 UI 验证与业务逻辑验证可以相互印证。落地清单如何为你的仓库写一份 FRONTEND.md综合原文档与 repo-template 配套体系一份合格的 FRONTEND.md 应包含以下要素均可对照原文档逐条核对目的声明一句话说明该文件为何存在——为 Agent 提供稳定的前端期望防止 UI 模式被随意发明UI 原则4 条清晰优先、流程可发现可重启、组件复用优先、可访问性属常规验证护栏5 条在docs/references/登记设计系统/组件库命名规则、spacing/typography token、状态变体、a11y 期望可参考 design-system-reference-llms.txt登记空/加载/成功/错误/重试等用户关键状态对照StatusBar.tsx与DocumentList.tsx的落地方式跨流程保持文案、键盘行为与视觉层级一致修复 UI bug 时同步新增/更新验证步骤关键旅程必须产生可执行证据。验证期望为每条关键用户旅程定义“浏览器或 runtime 验证步骤 证据落点计划或质量文档”视觉回归频繁时把截图/DOM 检查固化为标准步骤并将规则沉淀到docs/generated/生成物与docs/references/源参考的既有约定中。最后请记住 repo-template 的三条根本工作约定源自AGENTS.md工作每次只聚焦一个计划或特性切片“可执行证据”是完成的强制条件若同一类 review 反馈反复出现就把它提升为机械规则或 lint而不是在聊天里反复解释——FRONTEND.md 本身就是这条约定在前端领域的机械规则化产物。赞分享【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载相关推荐learn-harness-engineering 前端策略文档FRONTEND.md为编码 Agent 定义可验证的 UI 约束与设计系统守卫learn harness engineering 前端策略文档FRONTEND.md为编码 Agent 定义可验证的 UI 约束与设计系统守卫 本篇技术如何用免费开源眼动追踪工具实现视线控制电脑如何用免费开源眼动追踪工具实现视线控制电脑 想象一下仅凭眼睛就能控制电脑光标、点击链接、输入文字——这不再是科幻电影的场景而是开源项目eyetracker带用 FRONTEND.md 为编码 Agent 设定稳定可验证的 UI 预期learn-harness-engineering 仓库模板前端策略实战解析用 FRONTEND.md 为编码 Agent 设定稳定可验证的 UI 预期learn harness engineering 仓库模板前端策略实战解析 导读上一篇Hallmark 技能组件详解F5 注释截图Annotated Screenshot组件设计与实现下一篇PostHog 仓库同步故障工单排查 SQL 速查手册基于生产 Postgres 与 ClickHouse 的查询实战指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
