18trees-Project-Bootstrap

项目是什么

18trees-Project-Bootstrap 是一个个人定制化的 Bootstrap，面向支持 skills 的 Coding Agent（Codex / Claude Code）。它把四层语义地图、子 Agent 协作纪律，以及四个已验证的上游 skill 规范，集成为一次可用的项目初始化，默认以非侵入的方式装进你已经写了很久的项目。

它要解决的是：Agent 不知道你的项目长什么样，每次都要重新读代码，而你还得用文件路径和类名跟它说话；你想说「就改这一块」，却说不清这一块在代码里对应什么；改完了没有人独立检查。顺带一提，不少工具还会往仓库里塞文件，skills 目录和配置文件都变成提交历史的一部分。

对应地，它做三件事：给项目画一张四层语义地图，你在图上指着说「改这里」，Agent 负责映射到实现；给协作定一套纪律——每个任务一条分支、自动启动独立 Review、按队列串行合并；把好规范引进来，交互、编码、工程与可视化分别来自四个已验证的上游 skill，不另造一套。人只描述目标，安装、理解、修改、测试、独立 Review 与合并都交给 Agent；入口是目标项目的 Agent 对话框，网页版聊天机器人不能执行命令、读写文件，用不了这个项目。

具体结构

装进目标项目的东西分四块：一张四层语义地图、一套协作规程、一组来自上游的规范，和一条把它们装好、校验好、也能卸干净的本地工具链。

语义地图。 项目被投影成 Product / Feature（User Flow）/ Capability / System 四层，写成一份 project.manifest.json：节点带稳定的 NODE:X 编号、层级、名称、语义摘要与 planned / implemented 状态；关系分四类——相邻层之间的 contains、Feature 之间的顺序 precedes、同层的 depends_on，以及能力与系统之间的 data_flow；用户流程用 FLOW:X 列出有序的 Feature 步骤。JSON Schema 加一组额外校验保证编号唯一、层级合法、所有节点都能从 Product 到达、每个 Feature 至少进入一个流程。文件路径、类名与证据只写进 metadata，人看的那一层只有语义。地图由 archify 渲染成一份离线可查的自包含 HTML，首页第一入口是 Product / Feature Workflow；真相链是单向的——Codebase → Semantic Project Manifest → HTML Project Map。

协作规程。 主干是 Gateway Flow：main ← Merge Queue ← Review Gate ← Task Branch ← Coding Agent。每个任务基于最新 main 开一条 feat/、fix/、refactor/ 或 chore/ 分支，Coding Agent 禁止直接修改、提交或 push main；实现与测试完成后自动启动 Review Subagent，它只收到原始任务与验收、语义节点与边界、绑定 base / head 的 diff、测试结果与规范这五类材料，只读，只输出 PASS 或 REQUEST_CHANGES。合并队列按 Ready 顺序串行，队首每次同步最新 main 重新验证，冲突交回原 Coder 适配后再走一遍评审，Reviewer 不修代码。部署分 Local-first（默认）与 Production-direct 两种模式，进入生产前都要满足项目自定义的 Deployment Check。它交付的是行为规范：分支保护、权限和 CI / 队列服务要在远端自行配置。这个仓库自己的四个合并提交，就是按这套流程落的。

规范来源。 交互、编码、工程、可视化四层规范分别来自 i-have-adhd、ponytail、Stop That Shit 与 archify 四个已验证的上游 skill，上游正文不入库。项目刻意不新增竞争性的编码规范——不定义代码风格、测试规范和目录惯例；它的主要产出是把四者编排成一套：各自的适用边界在哪、Reviewer 按什么标准评审、上游缺失时怎么办、冲突时听谁的，并把这些结论固化进初始化模板。

工具链。 bootstrap.py 提供 init / map / validate / verify-install / deinit 五个入口；init 从项目外的完整源码副本执行，装进目标项目的副本负责生成地图、校验、核对安装与卸载。默认 Local-only：所有产物放进 .project-bootstrap/，根目录只留两个薄入口（Codex 的 AGENTS.override.md 与 Claude Code 的 CLAUDE.local.md），不修改已跟踪的 AGENTS.md / CLAUDE.md，也不动全局 Git 配置、共享 info/exclude、.gitignore 和索引——Git 条件配置只绑定安装所在的工作区。安装前后 tracked / staged diff 不变；卸载先预览范围，保留原规则与你的任务改动。显式选择 Standard 才会把规范随项目提交。运行需要 Python 3.12+、Node.js 22+、Git 与 archify，缺依赖时在项目外的缓存目录准备。

优秀设计

人在地图上说话，不在文件树上说话。 地图首页第一入口是 Product / Feature Workflow，不是文件树；人主要操作前三层，技术路径由 Agent 定位。同一份 manifest 服务两种读者：给人看的是可离线浏览的 HTML，给 Agent 的是定位实现的索引。

评审是默认动作，且不能由自审替代。 每个开发任务自动启动独立、干净上下文的 Reviewer，它只拿到五类材料、只读、只能给 PASS 或 REQUEST_CHANGES；证据不足时 REQUEST_CHANGES 是唯一选项——把「不许猜着通过」写进协议里，比写在提示词里可靠。

合并串行，旧的 PASS 不构成无条件合并依据。 队列按 Ready 顺序而非创建时间排序，队首要同步最新 main 重新检查；实现再改，原来的 PASS 即失效。冲突不交给 Reviewer 修，而是回到原 Coder 重新适配、重新测试、重新评审。

规范来自上游，不另造一套。 已经有经过验证的好规范，就用现成的；这个项目定义的是协作接口，不是新的编码规范。

安装非侵入、可回滚。 默认 Local-only 把效果限制在安装所在的工作区，不碰全局配置和项目已有规则；卸载能恢复原有排除文件字节与薄入口原内容，并保留你的任务改动。

解决了什么问题

• 下命令不必先读懂代码结构：需求按产品与功能语义提出，落地位置由 Agent 定位。
• 「只改这一块」成为可执行边界：Strict Node Boundary 下 Agent 不得越界，需要涉及其他节点时必须停下说明、等重新定义。
• 每次改动都过一次独立评审：Review 默认启动、干净上下文、只读，证据不足只能 REQUEST_CHANGES。
• 合并按 Ready 顺序串行，并针对最新 main 重新验证；冲突回到原 Coder 重新适配、重新测试、重新入队。
• 安装不打扰已有项目：安装前后 tracked / staged diff 不变，卸载可还原，规范随项目提交需要显式选择 Standard。
• 交互、编码、工程与可视化规范都不重造，分别沿用四个已验证的上游 skill。