setup-codebase-harness

搭建代码库 Harness

Harness 工程：模型是固定的——你要构建的是它周围的脚手架（环境、文档、反馈循环），让 Agent 能够以最少的人工关注构建和验证软件。人类负责引导；Agent 负责执行。你的任务是让代码库易于理解、可执行且可验证。

循序渐进、由深到浅地开展工作：评估现状，补上一个缺失的能力，再用它解锁下一个能力。不要试图一口气解决所有问题——只搭建代码库实际需要的部分。Agent 遇到困难时，解决办法几乎从来不是“再努力一点”——而是问自己：*“缺少什么能力？如何让它清晰易懂且可强制执行？”*然后把它加上。

此技能负责协调以下专注型子技能：dev-local-setup、e2e-setup、crabbox-setup（云端/并行）和 verifier-setup（搭建特定于代码库的 /verify 循环；取代旧的 pr 技能）。

0. 评估

调查代码库：技术栈、包管理器、服务/端口、基础设施依赖、现有文档/测试/CI，以及隐含的规则（埋在 README、PR 评论或人们的脑海中）。根据下面的各个支柱，记录缺失的部分。

1. 易于理解——Agent 能够理解代码库

Agent 看不到的东西就等于不存在。聊天记录或人们脑海中的知识都是不可见的——应将其写入有版本控制、位于代码库本地的文档中。

• a) 提供地图，而非手册。将根目录下的 Agent 文档（AGENTS.md / CLAUDE.md）精简为约 100 行的目录：一行概述、项目树、黄金规则（不可违背的约束），以及“该去哪里查”的表格。将详细内容移入结构化的 docs/ 信息系统（架构、前端、测试、领域主题），并添加 docs/index.md。庞大的指令文件会逐渐过时，还会挤占任务空间——让地图保持精简、稳定，并逐步披露详细信息。
• b) 编写能提供修复建议的自定义 lint。将黄金规则的文字描述转化为机械检查——只需记录一次人工判断，便可在每次运行时处处强制执行。每项约束对应一条 lint（分层/依赖方向、命名、禁止使用 any、禁止导入、文件大小、结构化日志）。编写能够直接给出修复方法的错误消息（“此处不允许使用 X——请改用 Y”），让修复建议进入 Agent 的上下文。将这些检查接入代码库的 linter 和 CI。
• **c) 可查询的代码图谱。**使用 codebase-memory-mcp 为代码库建立索引，让 Agent 通过知识图谱追踪调用方、数据流和架构，而不是盲目搜索——在大型代码库中导航更快、更精准。
• **d)（后续）保持文档准确。**添加文档新鲜度/维护检查，标记与代码不再一致的文档，并创建修复 PR。

2. 可执行——Agent 能够运行并驱动应用

• dev-local-setup → 通过一条命令启动可复现的本地技术栈（scripts/dev-local.sh up），运行所有服务和基础设施。
• 让应用可供驱动：通过 verifier-setup 安装的 playwright-cli 技能使用浏览器；确保日志可访问。
• crabbox-setup → 为每个 Agent 提供独立的云端环境——作为 dev-local 的安全并行方案。当循环并行运行时使用它：一台笔记本无法承载 N 套完整技术栈（固定端口、一个 Docker 守护进程、一个数据库），而每个工作树各自在本地运行也无法解决问题——这些工作树仍共用同一台主机。crabbox 为每个 Agent 提供独立的技术栈和盒内浏览器，让并行验证永不冲突。
• *进阶：*在本地运行临时的可观测性技术栈（可查询日志/指标），用于性能/可靠性提示词。

3. 可验证——Agent 能证明它确实有效

• e2e-setup → 可靠的端到端门禁：真实流程（不走捷径）、可复用的身份验证/会话助手、分层断言（客户端 → 服务端 → 产品）、视频/跟踪证据，以及仅用于沙盒的外部服务。
• verifier-setup → 为仓库搭建专属的 /verify 技能（发版前验证闭环）：由全新的 验证器子 Agent 驱动真实应用，确认刚构建的功能有效；主 Agent 持续修复，直到验证通过，运行编入流程的回归检查，并创建附有可审查证明链接的 PR。添加会话助手，让验证器能够访问需要登录的功能。

4. 其他——保持长期一致

• 提交规范：使用约定式提交 + 提交时格式检查/代码检查（例如 husky lint-staged + commitlint）。保持合并门禁轻量——Agent 吞吐量高时，修正成本低，等待成本高。
• 清理冗余：将“黄金原则”编码，然后定期执行清理，创建小型重构 PR——持续偿还技术债，而不是等到难以承受时才集中处理。一次性记录人类的品味，并在每一行代码中贯彻。
• 对正确性至关重要的改动进行 Agent 间审查（由独立审查者审查，而非自我审查）。

顺序与交付成果

1a（地图）→ 2（本地开发）→ 3（端到端 + verifier-setup），随后随着仓库成熟，再加入 1b（代码检查） 和 4。这些产物——精简的地图 + docs/、scripts/dev-local.sh、e2e/ 测试套件、生成的 /verify 技能和自定义代码检查——各自都是可复用、易于理解且会不断增益的能力。优先选择“朴实”、可组合、稳定且 Agent 能够完整建模的技术。