Practical Harness Engineering guides, templates, playbooks, and runnable demos.

This repository is organized around two main tracks:

• 通用智能体工程化
• 微服务智能体工程化

It is designed as a standalone open-source project for people who want to move from:

• "I know the concept"

to:

• "I can actually apply it in a real codebase"

• works/ 指南、模板、手册、清单
• practice/ 可运行示例
• INDEX.md 推荐阅读路径

harness-engineering-practice/
├── README.md
├── README.en.md
├── LICENSE
├── CONTRIBUTING.md
├── AGENTS.md
├── INDEX.md
├── works/
│ ├── general-agent-engineering/
│ │ ├── adoption-guides-and-roadmaps/
│ │ ├── agents-md-templates/
│ │ └── validation-loop-design/
│ └── microservice-agent-engineering/
│ ├── spring-blueprints/
│ ├── contract-testing-playbooks/
│ └── observability-integration/
└── practice/
 ├── 02-minimal-harness-demo/
 ├── 03-spring-service-template-demo/
 ├── 05-contract-testing-demo/
 ├── 06-observability-demo/
 ├── 07-openrewrite-demo/
 ├── 08-service-catalog-demo/
 └── 09-validation-review-demo/

目录说明:

• README.md / README.en.md:中英文首页
• INDEX.md:总阅读索引,适合第一次进入仓库时快速找阅读顺序
• AGENTS.md:仓库级入口说明,帮助智能体或维护者理解结构和验证方式
• CONTRIBUTING.md / RELEASE-CHECKLIST.md:贡献与发布前检查入口
• works/:文章、模板、手册、清单、教程
• works/general-agent-engineering/:通用智能体工程化内容
• works/general-agent-engineering/adoption-guides-and-roadmaps/:总览、路线图、清单、教程与架构对照
• works/general-agent-engineering/agents-md-templates/:中小团队仓库入口模板
• works/general-agent-engineering/validation-loop-design/:验证闭环与反馈回路设计
• works/microservice-agent-engineering/:微服务智能体工程化内容
• works/microservice-agent-engineering/spring-blueprints/:Spring / Java 微服务蓝图、模板与总览
• works/microservice-agent-engineering/contract-testing-playbooks/:契约测试、结构约束与相关清单
• works/microservice-agent-engineering/observability-integration/:可观测性方向的扩展入口
• practice/:可运行示例区
• practice/01-ralph-demo/:Ralph 编排与多角色循环样板
• practice/02-minimal-harness-demo/:最小 Python Harness Demo
• practice/03-spring-service-template-demo/:最小 Java / Spring 服务模板 Demo
• practice/05-contract-testing-demo/:最小契约测试 Demo
• practice/06-observability-demo/:最小可观测性 Demo
• practice/07-openrewrite-demo/:最小批量治理 / OpenRewrite 风格 Demo
• practice/08-service-catalog-demo/:最小服务目录 Demo
• practice/09-validation-review-demo/:最小验证闭环 Demo

• 概念到落地的总览文章
• 中小团队 AGENTS.md 模板
• 验证闭环设计
• 架构模式对照
• 团队实施路线图
• 一页式落地清单
• 从零到发布的实操教程

• Spring Cloud / Java 微服务落地蓝图
• Spring 微服务 AGENTS.md 模板
• 契约测试与可观测性 Playbook
• ArchUnit + 契约检查清单
• 微服务落地全景指南

• practice/02-minimal-harness-demo 一个最小 Python Demo,展示任务文件 + AGENTS.md + 测试门控
• practice/03-spring-service-template-demo 一个最小 Java 微服务模板,展示分层、ArchUnit、契约文件与 OTel 骨架
• practice/05-contract-testing-demo 一个最小契约测试 Demo,展示 provider verification 与 consumer 兼容性检查
• practice/06-observability-demo 一个最小可观测性 Demo,展示 trace id 贯通、日志关联与跨服务链路可见性
• practice/07-openrewrite-demo 一个最小 OpenRewrite Demo,展示批量治理、确定性重写与历史写法演进
• practice/08-service-catalog-demo 一个最小服务目录 Demo,展示平台元数据、仓库自描述与 owner/API/依赖入口
• practice/09-validation-review-demo 一个最小验证闭环 Demo,展示 lint、测试、AI review 与人工 review 的组合

1. works/index.md
2. works/general-agent-engineering/adoption-guides-and-roadmaps/harness-engineering-how-to-use-and-land.md
3. works/general-agent-engineering/agents-md-templates/mvp-agents-template-for-small-teams.md
4. works/general-agent-engineering/validation-loop-design/harness-validation-loop.md
5. works/general-agent-engineering/adoption-guides-and-roadmaps/harness-implementation-roadmap-for-teams.md
6. works/general-agent-engineering/adoption-guides-and-roadmaps/harness-checklist.md
7. works/microservice-agent-engineering/spring-blueprints/spring-microservices-harness-blueprint.md
8. works/microservice-agent-engineering/spring-blueprints/microservices-harness-guide.md
9. practice/02-minimal-harness-demo/README.md
10. practice/03-spring-service-template-demo/README.md
11. practice/05-contract-testing-demo/README.md
12. practice/06-observability-demo/README.md
13. practice/07-openrewrite-demo/README.md
14. practice/08-service-catalog-demo/README.md
15. practice/09-validation-review-demo/README.md

python -m unittest discover -s practice0円2-minimal-harness-demo\tests -p "test_*.py"
python -m unittest discover -s practice0円5-contract-testing-demo\tests -p "test_*.py"
python -m unittest discover -s practice0円6-observability-demo\tests -p "test_*.py"
python -m unittest discover -s practice0円7-openrewrite-demo\tests -p "test_*.py"
python -m unittest discover -s practice0円8-service-catalog-demo\tests -p "test_*.py"
python practice\\09-validation-review-demo\\tools\\validate_demo.py
python -m unittest discover -s practice0円9-validation-review-demo\tests -p "test_*.py"

cd practice0円3-spring-service-template-demo
mvn test

这个仓库不是为了把 Harness Engineering 讲成抽象理论。

它更希望帮助你:

• 写出更好的仓库入口文件
• 给 coding agents 补上结构与验证
• 在微服务体系里引入契约与可观测性
• 形成团队可以直接复制的 Harness 模式

MIT