# Harness **Repository Path**: haoxin963/harness ## Basic Information - **Project Name**: Harness - **Description**: 这是一个面向前端项目的 Harness Engineering 最佳实践样板：用清晰的架构、可执行的规则、阶段化 Skill、持久化变更记录和质量门禁，把 AI 编码从“单次对话技巧”升级为“可复用的工程系统”。 - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 2 - **Forks**: 0 - **Created**: 2026-05-10 - **Last Updated**: 2026-05-13 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Harness Frontend Scaffold [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) [![Node](https://img.shields.io/badge/Node-20+-green.svg)](https://nodejs.org) [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org) [![pnpm](https://img.shields.io/badge/pnpm-9+-orange.svg)](https://pnpm.io) > 让 AI Agent 像成熟前端团队的一员一样工作。 > > 这是一个面向前端项目的 **Harness Engineering 最佳实践样板**：用清晰的架构、可执行的规则、阶段化 Skill、持久化变更记录和质量门禁，把 AI 编码从“单次对话技巧”升级为“可复用的工程系统”。 ## 为什么需要 Harness Engineering AI 已经能写代码，但真实项目里更难的是让它持续、稳定、可审计地交付。 常见问题不是模型不会写 React，而是： | 真实问题 | Harness 的做法 | | --------------------------------- | ------------------------------------------------------------ | | 每次新会话都要重新解释项目结构 | 用 `.harness/wiki` 和 `.harness/agents` 保存项目地图与角色上下文 | | Agent 把文件放错层、跨层乱 import | 用 FSD 分层规则、ESLint 和 `scripts/check-deps.mjs` 守住依赖方向 | | “我改好了”但没有证据 | 用 `pnpm run ci`、Vitest、Playwright、MSW 作为程序化门禁 | | 需求、评审、测试散落在聊天记录里 | 用 `.harness/changes/{change-id}` 保存完整审计轨迹 | | 同一个错误反复出现 | 把教训升级成 Rule、Skill checklist、lint rule 或 CI check | **Harness Engineering 的核心思想**：不要只优化 prompt，要设计一套让 Agent 不容易跑偏、出错可定位、经验可沉淀的工程环境。 ## 这个仓库提供什么 这个项目不是空模板，也不是只给 Agent 看的文档集合。它包含一套可以运行、可以测试、可以迁移的前端工程样板： - 一个完整的 React 前端应用：登录、注册、用户列表、用户详情、修改密码。 - 一套 Feature-Sliced Design 分层：`pages -> features -> entities -> shared`。 - 一套 `.harness/` 体系：Agents、Rules、Skills、Wiki、Changes、Templates。 - 一套质量门禁：TypeScript strict、ESLint、Prettier、Vitest、Playwright、MSW。 - 一套面向 AI 协作的 11 阶段流程：需求分析、评审、编码、测试、CI、E2E、部署验证、用户确认。 你可以把它当作： 1. 学习 Harness Engineering 的最小完整案例。 2. 新前端项目的工程脚手架。 3. 给现有项目迁移 AI 工作流的参考实现。 4. 团队内部制定 Agent 开发规范的模板库。 ## 快速开始 ```bash # 1. 安装依赖 pnpm install # 2. 初始化 MSW worker（首次 clone 后执行） pnpm dlx msw init public/ --save # 3. 启动本地开发 pnpm dev # 访问 http://localhost:5173 ``` 验证项目健康度： ```bash pnpm run ci # typecheck + lint + format:check + test + build pnpm test:e2e # Playwright E2E pnpm harness:doctor # .harness 体系自检 ``` ## 一次标准变更如何发生 Harness 的目标不是让 Agent “更自由”，而是让 Agent 每次都走相同的可靠路径。 ```bash # 创建一次变更的审计目录 pnpm harness:new-change feat user-export ``` 然后在 AI 编码工具里提出需求： ```text 我要给用户列表加一个导出 CSV 按钮。 导出当前搜索条件下的用户，文件名包含当天日期。 不需要后端真实下载接口，前端生成即可。 ``` Agent 应该按 11 阶段推进： ```text 1 需求分析 -> 2 需求评审 -> 3 编码实现 -> 4 编码评审 -> 5 测试编写 | 7 代码推送 <- 6 测试评审 <-+ | 8 CI 验证 -> 9 E2E 测试 -> 10 部署验证 -> 11 用户确认 ``` 每个阶段都有明确产出和门禁。比如需求阶段产出 `spec.md` 和 `tasks.md`，编码阶段必须通过 typecheck，测试阶段必须补单测和关键路径 E2E，最终交付前必须有可验证证据。 ## `.harness/` 是项目的第二套源代码 业务代码告诉浏览器怎么运行，`.harness/` 告诉 Agent 怎么工作。 ```text .harness/ ├── agents/ # Agent 角色与调度中枢 ├── rules/ # 不可绕过的工程红线 ├── skills/ # 每个阶段的操作手册 ├── wiki/ # 架构、领域模型、API 契约 ├── changes/ # 每个需求的审计轨迹 ├── templates/ # 新 change 的目录模板 └── mcp/ # 外部工具与 MCP 配置索引 ``` 建议先读这几个文件： | 文件 | 你会理解什么 | | ------------------------------------------------------------ | ----------------------------------------- | | [CLAUDE.md](CLAUDE.md) | 每次会话启动时 Agent 应该加载的最小上下文 | | [.harness/agents/frontend-owner.md](.harness/agents/frontend-owner.md) | Application Owner 如何调度 11 阶段流程 | | [.harness/rules/project-structure.md](.harness/rules/project-structure.md) | FSD 分层和依赖方向红线 | | [.harness/rules/dev-workflow.md](.harness/rules/dev-workflow.md) | 每个阶段的入场条件、产出、门禁和回退路径 | | [.harness/wiki/architecture.md](.harness/wiki/architecture.md) | 项目架构、数据流和状态管理边界 | ## 前端架构 ```text src/ ├── app/ # 应用入口、Router、Provider、全局样式 ├── pages/ # 路由页面，只做组合和页面级状态 ├── features/ # 用户可感知的业务能力 ├── entities/ # 领域模型、Zod schema、纯 API 封装 ├── shared/ # http client、MSW、通用基础设施 └── test/ # 测试工具和 provider 封装 ``` 关键约束： - `pages -> features -> entities -> shared` 单向依赖。 - 外部数据进入应用前必须经过 Zod 校验。 - 服务端状态使用 TanStack Query。 - 客户端会话状态使用 Zustand。 - API mock 使用 MSW，单测和开发环境共用同一组 handler。 - 质量门禁必须可程序化执行，不能只靠自然语言承诺。 ## 技术栈 | 类别 | 选型 | | ---------- | ----------------------------- | | 构建 | Vite 5 + TypeScript 5 | | UI | React 18 + React Router 6 | | 服务端状态 | TanStack Query | | 客户端状态 | Zustand | | 数据校验 | Zod | | Mock | MSW | | 单元测试 | Vitest + Testing Library | | E2E | Playwright | | 规范 | ESLint flat config + Prettier | | 包管理 | pnpm 9 | ## 你可以从这里学到什么 - 如何把 AI 编码流程拆成可审计、可回退的阶段。 - 如何用 FSD 降低 Agent 修改前端代码时的影响半径。 - 如何把“项目约定”从聊天提示词沉淀成 repo 内的 Rules 和 Skills。 - 如何用 MSW、Vitest、Playwright 给 Agent 输出建立真实反馈环。 - 如何把一次失败的经验升级成下一次不会再犯的自动化约束。 ## 文档导航 | 文档 | 适合什么时候读 | | ----------------------------------------------------- | --------------------------------------- | | [AUTHORING-GUIDE.md](docs/AUTHORING-GUIDE.md) | 想完整理解谁写什么、如何跑一次真实需求 | | [HARNESS-USAGE-GUIDE.md](docs/HARNESS-USAGE-GUIDE.md) | 日常使用、排错、迁移 Harness 到其他项目 | | [HOW-TO-RUN-LOGIN.md](docs/HOW-TO-RUN-LOGIN.md) | 想看登录功能从需求到交付的完整 replay | | [CONTRIBUTING.md](CONTRIBUTING.md) | 想贡献代码、文档或 Harness 规则 | ## 迁移到你的项目 如果你已经有一个前端项目，可以按这个顺序迁移： 1. 复制 `.harness/rules`，先建立不可商量的工程边界。 2. 复制 `.harness/wiki`，把架构、领域模型和 API 契约改成你的项目事实。 3. 复制 `.harness/skills`，按你的技术栈调整每个阶段的 checklist。 4. 引入 `scripts/check-deps.mjs` 或等价脚本，把关键规则变成自动检查。 5. 从一个小需求开始使用 `.harness/changes`，不要一开始就迁移所有历史。 优先迁移“能被机器检查的约束”，再补文字规则。能放进 lint、typecheck、test、CI 的东西，不要只写在 README 里。 ## 贡献方向 欢迎贡献： - 更好的 Harness Rule / Skill 设计。 - 可复用的前端质量门禁脚本。 - 真实项目迁移经验。 - 新的 E2E、MSW、CI、部署验证实践。 - 文档翻译、案例 replay、教学材料。 如果你发现 Agent 在某类任务里反复犯错，最有价值的 PR 不是只修一次代码，而是把这个错误变成以后无法绕过的规则、脚本或 checklist。 ## 参考 - Anthropic: [Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) - Anthropic: [Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps) - OpenAI: [Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/) - Mitchell Hashimoto: every repeated agent mistake should become a stronger harness constraint. ## License [MIT](LICENSE) © 2026 Haoxin