メニュー
一次性初始化适合 AI 协作开发的轻量工程治理骨架（docs/INDEX、ADR、module、roadmap、ACTIVE_CONTEXT、AGENTS.md / CLAUDE.md）。新仓库 / 文档结构混乱 / 项目内文档治理初始化时调用。【定位】独立可用、不需要多 agent 编排；也是 cto-orchestration 新项目接入的第一步，但小项目只做文档治理时单独用即可。一次性建结构，区别于循环跑的 cto-orchestration。
Codex または Claude でインストール この Prompt をコピーして Codex、Claude、または他のアシスタントに貼り付けると、Skill ページを確認してインストールできます。
SOC 職業分類に基づく
| name | repo-governance-bootstrap |
| version | 1.3.0 |
| description | 一次性初始化适合 AI 协作开发的轻量工程治理骨架（docs/INDEX、ADR、module、roadmap、ACTIVE_CONTEXT、AGENTS.md / CLAUDE.md）。新仓库 / 文档结构混乱 / 项目内文档治理初始化时调用。【定位】独立可用、不需要多 agent 编排；也是 cto-orchestration 新项目接入的第一步，但小项目只做文档治理时单独用即可。一次性建结构，区别于循环跑的 cto-orchestration。 |
用户说出以下任一：
跳过条件：仓库已有 docs/INDEX.md 和 docs/ACTIVE_CONTEXT.md → 提演化方案、不重新初始化；绝不覆盖既有治理文件。
future_plan.md / ideas.md / generic TODO dumpdocs/
├── INDEX.md
├── ACTIVE_CONTEXT.md # 当前焦点 / hot context
├── NORTH_STAR.md # 可选：长期架构方向（伞仓或有明确长期方向的仓）
├── decisions/
│ └── ADR-0001-<slug>.md # 仓库边界（ADR 编号固定 4 位）
├── modules/
│ └── <module>.md # 每个核心模块一个 flat 文件
└── roadmap/
├── README.md # status-bucket 索引（Active / Deferred / Obsolete）
├── active-roadmap.md # 单文件，inline Status
├── deferred/
│ └── README.md # deferred 索引（Items 表 + Entry Criteria + Promotion Rule）
└── obsolete/
└── README.md # obsolete 索引（仅索引，少用）
AGENTS.md # repo 治理规则（Codex 读）
CLAUDE.md # 一行：@AGENTS.md（Claude 读）
scripts/engineering-gate.sh # 后端 repo-owned fix/check/test 稳定接口（有代码 marker 时）
scripts/engineering-gate.conf # 初始化时固化 profile + module root，不在每次运行时猜
.githooks/pre-commit # docs-check → engineering check → local test
ACCESS.local.md / .env # gitignored — 元数据+名字+gotcha / 值(KEY=VALUE, 600)
定位分工：本 skill = 结构层（一次性生成骨架 + 写入纪律 + 机检门）；循环层的防腐 （收口三同步 / 复盘 / 教训分层沉淀）由编排 skill 承担（
cto-orchestration§5 +orchestrator-core铁律九），其项目宪法拷贝即本 skill 生成的 AGENTS.md §6。腐烂是 workflow 问题——没有门校验， 任何结构都会漂；快照类整篇重写、知识类逐条增改、决策类只增不删，三种纪律别互串。
| 产物 | 寿命层 | 更新纪律 | 防腐机制 |
|---|---|---|---|
AGENTS.md 宪法 | 慢·治理变量 | 逐行准入："删了这行 agent 会犯错吗？"不会 → 删；代码能推出的不写 | 尺寸门 <200 行（超长被降权）/ 32KiB（超限被 harness 静默截断） |
| ADR | 只增·决策史 | 不可变；翻案标 superseded by、不删；1-2 页对未来开发者说全句 | 4 态状态机；组件 ADR 带 Owner/Sunset/Review-by |
| module FOR/NOT FOR | 慢·边界 | 随触及它的代码同一 commit 更新 | 边界冲突显式上报（宪法 §3） |
| roadmap | 中·映射层 | 只映射外部任务 SoT、不复制状态（任务状态是高频信息，天然不属于常驻 docs；两套账本必烂一套） | 三桶 + 6 态词汇；沿用外部 ID |
ACTIVE_CONTEXT | 快·快照 | 收口整篇重写 ~60 行，快照非日志（实证：被当日志 append，4 天 190 行冻结腐烂） | freshness 门 + 收口三同步（宪法 §6） |
ACCESS.local | 本机·含密 | 写时脱敏；gitignored 永不提交 | gitignore + 提交前 redaction sweep |
INDEX | 慢·traffic cop | 只放链接——超过一行说明的内容 = 放错了地方 | 死链门 |
NORTH_STAR（可选） | 最慢·方向 | 仅 maintainer 修订、semver 版本化（细则在模板注）；ADR 记历史、它记方向 | 原则带稳定 NS-ID 被评审 brief/门禁引用（没人检查的原则是注释）；与 accepted ADR 冲突不择边、升级 maintainer |
细则（判据级；模板全文见 references/templates.md）：
Status:；deferred 一项一文件
<PREFIX>-DEFER-NNN-<slug>.md（<PREFIX> 按项目取，勿硬编码他人前缀）；obsolete 仅索引。
不建 generic backlog（future_plan.md / ideas.md / TODO dump）——未来工作进 deferred。modules/<m>.md，复杂到三份独立维护再拆目录；ADR 编号 4 位零填充全仓一致。ACCESS.local.md（gitignored）三段式（接入凭证 / 环境拓扑 / 验证配方）：committed 骨架答
what/why，它答"怎么真正连上"；凭证 canonical home = 外部 vault、此文件是本机缓存；拓扑与凭证有意
同进一份（内网拓扑本身也是敏感面）。高频两坑（凭证间接——存 X 读 Y 必记桥接，demo-day 401 头号
根因；活体 auth smoke 先跑并读失败模式）已固化在模板注释。建文件即写进 .gitignore。docs/，换来变更
历史 + 误删恢复 + 派工漂移审计（实证：agent 误删关键 docs 无版本可恢复）；加 remote 前先 secrets sweep。NORTH_STAR.md 放伞仓 docs/，子仓 AGENTS.md 指向它（按 NS-ID
引用）；②AGENTS.md 覆盖检查——每个含自有 .git 的一级子仓必须有根 AGENTS.md（Tier-1 活跃仓用
PROJECT_AGENT.md 全量宪法，维护型仓用 templates.md 的 minimal 变体 <60 行即达标），一行
shell 即可做成门（one-liner 见模板注）；③nearest-wins：伞仓根管跨仓规则，子仓管自己内部，两层各 <200 行、不复读对方。询问用户（如果未提供）：
pyproject.toml(Python)、go.mod(Go)、
mvnw + pom.xml(Java/Maven)、gradlew + build.gradle[.kts](Java/Gradle)、Cargo.toml(Rust)。
单根 / 明确多根直接固化 profile；仅 Maven/Gradle 并存或 monorepo module root 不明确时再问。创建目录骨架：docs/decisions/、docs/modules/、docs/roadmap/deferred/、docs/roadmap/obsolete/（roadmap 三桶一次建好）。
生成 docs/INDEX.md：含 Decisions / Modules / Roadmap / AI Context 四节 + Traceability 表（| Capability | Component | ADR | Roadmap |）。
生成 docs/decisions/ADR-0001-<slug>.md：用 references/templates.md 的 ADR 模板，主题是"仓库定位与边界"——记录这个仓库 FOR 什么 / NOT FOR 什么。Status: proposed 起步，由用户后续确认为 accepted。
生成 docs/modules/<m>.md：每个核心模块一个文件，含 FOR / NOT FOR / Components / Evolution 节。
生成 roadmap：roadmap/README.md（三桶索引）+ roadmap/active-roadmap.md（≥1 item，每项含 Status / Capability / Components / ADR / Acceptance Criteria）+ roadmap/deferred/README.md（空 Items 索引 + Entry Criteria + Promotion Rule）+ roadmap/obsolete/README.md（空索引）。三桶总索引与 obsolete 索引 freeform（一行表 + 链接即可，无模板）。
生成 docs/ACTIVE_CONTEXT.md：当前焦点 + 在跑/在等的 workstream 表 + standing constraints + recent decisions（最近 3–5 条）。按"治理系统观"的快照契约生成，头部带契约声明（模板见 references/templates.md）。
生成 AGENTS.md（守尺寸预算：<200 行——超长文件被 agent 静默降权/截断，见治理系统观表）：以 references/PROJECT_AGENT.md（中文成品宪法）为准落地，按其章节：Source of Truth 优先级 / 三档工作模式 / 模块边界（FOR / NOT FOR）/ Capability vs Component / 状态词汇 / 文档治理（已含文档生命周期 anti-rot：ACTIVE_CONTEXT 快照契约 + 收口归档仪式）/ Code Traceability / Engineering Gate / 完成标准。Engineering Gate 写入实际启用的 profile/module root、repo-owned 三命令与规范指针；不复制各语言类型条文。工具偏好若全局 agent 配置未覆盖项目特定项（如子仓库 toolchain）再补。Redaction 边界写明一条：secret/凭证只进 ACCESS.local.md（gitignored）与外部 vault，永不进 committed tree / traces / 日志 / 对外消息——避免 AGENTS.md 里 "creds never in repo tree" 与本机存明文凭证的口径自相矛盾。
生成 CLAUDE.md：单行 @AGENTS.md。
生成 ACCESS.local.md + 值文件孪生 ACCESS.local.env 并写进 .gitignore：按 references/templates.md 的 ACCESS.local 模板建三段式骨架（值/元数据物理分离：.md 只留元数据+秘密名字+gotcha，值进纯 KEY=VALUE 的 .env 孪生并 chmod 600；注入 set -a; source; set +a，判据与金丝雀纪律指针 agent-backend-standard 附录 E），字段留空待用户填实；.gitignore 加 ACCESS.local.* 与 .env* 两行（带注释说明含 creds、永不提交）；同步在项目 .claude/settings.json 的 permissions.deny 写入 env 值文件的 deny 面（Read(ACCESS.local.env)、Read(**/ACCESS.local.env) + Bash 全系 display 模式 cat/grep/head/tail/less/more/sed/awk/strings/sort/cut/od/xxd/base64 作用于该文件——定位=防失手不是沙箱）。deny 生效需会话重启加载：告知用户重启后用假数据金丝雀验证（Read + 各 Bash 形态全拒才算在位），未验证前勿放真值。绝不把真实凭证写进 stub。
配置 memory-discipline hook（默认项目级，直接建）：把 references/memory-discipline-hook.py 接成
PostToolUse hook——写 memory/*.md(非 MEMORY.md) 时确定性注入"事实细节→ACCESS.local.md/docs、只留指针"提醒。
默认写项目级配置（.claude/settings.json 等，blast radius 小、随 bootstrap 直接建不必问）；只有要全局跨项目
才问用户写 ~/.claude/。为什么需要 hook：该纪律在 cto-orchestration §5，但 skill 文本随长对话
salience 衰减，高频纪律须 hook 强制层兜底。三 agent wiring（CC/codex/omp 实测字段与坑）见 references/hook-wiring.md；绝不把真实 secret 写进 hook。
建组合 project gate：
references/docs-check.sh → scripts/docs-check.sh。四检 = AGENTS/CLAUDE 尺寸门 · docs
相对链接死链（FAIL）· ACTIVE_CONTEXT 新鲜度与行数 · 幻影路径引用。references/engineering-gate.sh → scripts/engineering-gate.sh，
按 references/engineering-gate.conf.example 生成 scripts/engineering-gate.conf，显式列出每个
Python / Go / Java-Maven / Java-Gradle / Rust profile 与相对 module root。语言命令与失败契约的
canonical = agent-backend-standard 附录 C §1–§6；本 skill 只负责初始化。pyproject.toml + uv.lock；Go 的 staticcheck/golangci-lint 进 repo-owned 版本清单 / bootstrap；
Java 只选一个 committed wrapper，固定 Spotless/Checkstyle plugin 与 lifecycle wiring；Rust 用
rust-toolchain.toml 固定 channel + rustfmt/clippy components。大仓可把模板的本地 test 分支改成
AGENTS 明示的 deterministic focused suite；CI 仍跑附录 C 全量收口。references/pre-commit.sh → .githooks/pre-commit 并赋可执行权限。顺序固定为
docs-check → engineering check → engineering test；hook 不跑 fix，避免 staged index 仍含旧内容。core.hooksPath 为空时设 .githooks；已存在 hooksPath、.git/hooks/pre-commit 或 pre-commit
framework 时合并调用，绝不覆盖。CI 已存在时同步调用同一 wrapper；本地 hook 可被
--no-verify 绕过，不能冒充 required CI。fix/check/test（fix 后 review diff + re-stage），再用 hermetic
失败探针证明工具非零、gate/config 半安装都会阻断且输出 failed/fix/retry/AGENTS + canonical 指针。
docs-only repo 只启用 docs-check（engineering script/config 均不存在）。完成时报告：列出已建文件 + 用户下一步建议（填实 ADR-0001 内容 / 完成首个 module 的 FOR-NOT FOR / 把第一个 roadmap item 标 active / 在 ACCESS.local.md 填本机接入凭证与验证配方 / 若配了 hook 跑一次 memory 写入确认提醒生效 / 收口后重跑 docs-check.sh 养成节奏）。
两套词汇独立、不可互换：ADR 4 态（Nygard）/ Roadmap 6 态。完整定义见
references/PROJECT_AGENT.md §5（canonical——它随成品写进项目 AGENTS.md，必须自包含）。
生成 ADR / roadmap 时按那里取值，本 skill 不复述全文，只守一条易错点：别把 ADR 的
accepted 安到 roadmap 上、别把 roadmap 的 active/completed 安到 ADR 上。
生成物模板（ADR / 组件引入 ADR lifecycle 变体 / 模块 / roadmap 条目 / deferred 条目 /
deferred 索引 / ACTIVE_CONTEXT / ACCESS.local / INDEX / NORTH_STAR / AGENTS.md minimal
变体）→ references/templates.md（顶部有目录）。
两条主干级判据：
Owner / Sunset Criteria / Review-by 三段，
防引入后无人清理沦为死基础设施（更细的 lifecycle 规则见 agent-backend-standard 附录 A，本骨架只建槽）。完成后：
docs/INDEX.md 单文件即可定位所有 source of truthAGENTS.md + CLAUDE.md 生效，agent 进入新对话能识别上述结构fix/check/test、组合 pre-commit 与 actionable failure 指针均已实跑完成后告诉用户：
AGENTS.md 管理（Source of Truth 优先级 / 状态词汇 / 三档工作模式 / 等）obsolete / rejected 不删engineering-gate.sh fix，提交门跑 non-mutating check + local test，CI 跑全量收口CTO/orchestrator 模式管理多 agent 软件交付：agentctl 统一派工（一条 duplex lane、三引擎原生协议，轮内 steer）、goal 合同驱动、typed watcher、异构评审、真路径验收与主理人减负。适用于用户要求'你做 CTO/编排者'、'派 omp/codex 去做'、'goal 模式派发'、管理多会话开发或把这套工作流接入新项目。新项目先用 repo-governance-bootstrap 建治理骨架。不要用于单 agent 小任务、无需评审循环的局部改动或纯文档初始化。
多编排者/长期 agent 身份之间的异步信箱总线——发信、收信、回信、归档、名册注册。每个身份一个 inbox，一封信只有一个去处（收件人 inbox），收信只查自己信箱。触发：给另一个编排者/CTO/agent 写信或提议、查我的信箱、跨编排者协调、看有哪些注册身份。不用于人类电子邮件（gmail/给真人同事或客户写信）或普通消息转发。可选伴随 cto-orchestration 使用（多编排者场景）。Use when writing to / reading mail from another orchestrator agent, coordinating across orchestrators, or managing the agent roster; NOT for human email.
生产级 agent 时代后端工程手册(hub)——建 / 评审 agent·LLM 后端、**任何碰 DB 的持久层后端**、或为任何后端建立 / 评审 repo 工程门禁时加载。覆盖:架构与控制流、上下文与 prompt 工程、工具设计(ACI)、记忆与状态、检索/RAG、韧性与幂等、人在环、安全护栏与生成操作的有界执行、评估、可观测与成本、代码/依赖生命周期与反死代码、**数据访问纪律(连接·读·写事务)**、**缓存纪律(准入·失效治理)**、**秘密接触面纪律(分离·deny·金丝雀)**、Python/Go/Java/Rust 统一 `fix/check/test` 工程接口与门禁、规范治理。本文件是目录,深度按需读 references/。可观测性/Git/A2A 对外契约是独立 skill,本 hub 交叉引用不重复。Use when building or reviewing agent/LLM backend code, ANY backend touching a database, or establishing/reviewing repository engineering gates for a backend: architecture, prompts, tools, memory, RAG, resilience, HITL, safety and bounded execution, eval, cost, code/dependency lifecycle, data access, and the Python/Go/Java/Rust fix/check/test gate interface.
生产级 Git 协作 SOP——受保护分支(main/master/develop/dev/release/**/project/*)按仓库 tier 执行服务端门禁(Tier 1 禁 force/delete;Tier 2 要求 PR 且默认允许 self-merge;Tier 3 显式接入 required CI)、改动从 feature 分支起、base 移动且与你改动重叠才 rebase、集成策略默认 squash、提交不加 AI 签名。任何 git commit / push / 开 PR / 建分支 / 合并场景加载;agent 写完代码准备提交前必读。Use when committing, pushing, opening a PR, branching, rebasing, or merging in any company repo.
生产级可观测性与工程规范,适用于**所有后端服务** —— 普通微服务(auth / 网关 / 业务服务)与 agent / 多 agent / RAG 知识库项目通用。核心:用 trace_id 串 trace/log + 业务 id 反查 db、结构化日志、OpenTelemetry 埋点、跨进程 W3C traceparent 传播、日志级别纪律、边界类型纪律(含 id 持久化:不往业务行塞 trace_id);agent / RAG 场景在此基线上加 LLM / 工具 / 检索埋点与 GenAI 语义约定。Use this skill whenever writing or reviewing backend code that involves logging setup, OpenTelemetry tracing, structured logs, cross-process context propagation, choosing log levels (INFO vs DEBUG), correlating logs / traces / db to debug, defining types for boundary or inter-service data — and additionally agent orchestration / sub-agents, LLM / tool / retrieval calls, or GenAI semantic conventions. 适用 Python / Go / Java / Rust。Apply it even when the user only says things like "加点日志" "接一下 trace / instrument this" "set up observability" "这个错误怎么查不到" "这个请求怎么追踪",不限于显式提到规范时。目标:trace_id 串 trace/log、业务 id 反查 db,让线上问题最快定位。
多智能体编排的领域无关内核（A² Supervisor 层的方法论抽象）。把编排者的操作系统从领域里剥出来：萃取式主上下文 + 按『要不要主上下文』切分派工 + 契约化派发 + 分层合并 + 对抗式异构验证 + 降认知负载。领域皮（CTO 写码 / 总编内容 / 未来任意领域）只贴一张薄角色表 + 完成定义，内核整套复用。适用于用户要求抽象编排模式、造新领域编排者、或问『多智能体架构怎么搭』。不要用于：单 agent 一次性小任务（无需内核）、纯文档初始化（用 repo-governance-bootstrap）。派工/评审/状态落盘的领域实现见各皮 skill（cto-orchestration / yangge-ops）。