Legibility（可读性/可见性）

Legibility（可读性/可见性）是Harness Engineering的基石概念，指代码库、日志、测试、部署管道等系统对AI Agent的透明度和可理解程度。它决定了AI Agent能发挥多大杠杆作用。

核心原则

系统对AI Agent的可见性直接决定杠杆大小。如果AI Agent无法"看懂"系统，就无法进行有效的推理、修改和修复。

实践要求

1. 代码库可读：Monorepo让Agent能遍历整个代码树，进行跨模块依赖分析
2. 日志可读：所有服务输出结构化日志，AI Agent能读取并诊断问题
3. 测试可读：Agent能在本地运行完整的集成测试和E2E测试
4. 部署管道可读：CI/CD管道确定性强，Agent可预测失败结果
5. 架构可观测：Agent必须能像人类高级工程师一样"看到"系统边界、状态机、数据流

实现方式

• Monorepo：统一代码仓库，提升上下文完整性和本地验证闭环能力
• 渐进式上下文加载：结合Agent skills + 结构化检索（RAG-like），只加载当前任务相关的子树
• 结构化日志：所有服务输出结构化日志，确保AI Agent能读取
• 标准化管道：无人工override，管道确定性强

重要性

Legibility是Harness Engineering的底线要求。如果AI读不到日志，就无法诊断；如果代码库碎片化，Agent就无法进行跨服务推理。提升Legibility是构建AI-First工程系统的第一步。