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 practice\02-minimal-harness-demo\tests -p "test_*.py"
python -m unittest discover -s practice\05-contract-testing-demo\tests -p "test_*.py"
python -m unittest discover -s practice\06-observability-demo\tests -p "test_*.py"
python -m unittest discover -s practice\07-openrewrite-demo\tests -p "test_*.py"
python -m unittest discover -s practice\08-service-catalog-demo\tests -p "test_*.py"
python practice\\09-validation-review-demo\\tools\\validate_demo.py
python -m unittest discover -s practice\09-validation-review-demo\tests -p "test_*.py"

cd practice\03-spring-service-template-demo
mvn test

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

它更希望帮助你：

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

MIT