claude-writ

技能简介

claude-writ 是 Claude Code 的本地治理、上下文与连续性运行时。它解决了一个根本性问题：系统提示词、CLAUDE.md、方法论文档都依赖模型"记住"规则——但当上下文填满、会话压缩、或模型判断规则本次不适用时，这些指令就会失效。writ 不替代指令，而是增加第二层原语：对于你选择门控的工作流环节，writ 在工具执行时强制执行这些规则，无论模型注意力如何。

writ 提供三大核心能力：Action（工具时间控制，可允许、暂停、确认或拒绝操作）、Context（相关规则、技能和方法论在工作需要时送达）和 Continuity（决策和项目记忆跨会话持久化，跨上下文压缩保留最佳努力交接）。

核心能力

1. 计划门禁与测试门禁：在 Work 模式下，源代码写入被阻断，直到人类先批准计划（输入 approved），再批准测试（再次输入 approved）。两道门全部开启后，实现写入才被允许，两个门均读取人类键入内容，Agent 无法自我批准。
2. 凭证保护：对密钥、.env 文件和 SSH 材料的写入在每种模式下均被拒绝，凭证路径无需打开文件即可被分类保护。
3. Shell 写入检查：通过重定向、tee、cp 或 sed -i 进行的写入与工具写入走相同的检查路径，不存在单独的弱化检查。
4. 决策溯源（Decision Memory）：批准的方案、治理规则、变更文件和结果提交机械链接而非从对话推断，记录可作为新会话简报、git notes 和支持的 Pull Request 评论回放。writ recall 可读取该记录。
5. 自动记忆镜像：Claude Code 自身的内存文件在被写入时同步镜像到图数据库中，按项目作用域组织，支持 writ memory backfill、writ memory list 和 writ memory audit。
6. 上下文压缩交接：对话被压缩时，writ 写出派生记录（模式、阶段、批准状态、计划声明的文件、实际写入的文件、未完成项、加载的规则），下一条提示词引导 Agent 找到该记录。
7. 多模式Governance：conversation（无门禁）、review（供应审查指导）、investigate（捕获 Web 引用和命令证据）、debug（阻断源编辑直到写出根因）、work（需要计划+测试批准）。
8. 混合检索：结合精确词项和语义搜索，通过图关系引入关联指导，带有弃权门（无相关内容时不填充噪声）。
9. 子Agent授权控制：辅助 Agent 被拒绝任何其编排者在当前时刻会被拒绝的路径，每个角色携带自己的写入作用域。
10. 凭证文件强制拒绝：无论服务是否可达，写入凭证文件在每种模式下均被拒绝，且批准 Token 无法在无人参与情况下被创建或消费。

安装配置

前置条件：Claude Code、Python 3.11+、Docker（Python 是真实依赖，不只是打包便利；Docker 运行存储规则、方法论、项目记忆和决策记录的图数据库）。

1. 方式一：让 Claude Code 自动安装（推荐）：

claude plugin marketplace add infinri/Writ claude plugin install writ@writ

启动 Claude Code，writ 检测到未完成引导并打印一行命令，粘贴运行后重启 Claude Code 即可完成环境、数据库、规则、后台服务和权限配置。该脚本是幂等的，重新运行即为完整更新流程。

2. 方式二：手动验证后由 Claude Code 处理剩余步骤：

安装 Writ（https://github.com/infinri/Writ），验证 Python 3.11+ 和 Docker 可用，跟随插件安装说明，运行 Claude Code 启动后打印的引导命令，重启 Claude Code，验证 writ status 健康。

3. 验证安装：

writ status

服务不可达时，钩子默认放行而非阻断（基础设施故障不应锁定你的代码库）；设置 WRIT_STRICT=1 可将写入路径反转为严格模式。

使用步骤

1. 安装并引导 Writ：

claude plugin marketplace add infinri/Writ claude plugin install writ@writ

首次启动后运行打印的引导命令，配置 Python 环境、Docker 图数据库和规则库。

2. 选择工作模式：

告诉 Writ 你在做什么工作（模式）。模式可自动建议、显式设置或临时切换：

writ mode work # 切换到 Work 模式

不同模式的治理行为不同（见核心能力第7条）。

3. 在 Work 模式下提交计划并等待批准：

Claude 提出实现计划后，如需写入代码，Writ 阻断写入并提示：

[ENF-GATE-PLAN] ALL writes blocked -- plan not yet approved. DO NOT attempt more writes. Present your plan to the user and say: "Say approved to proceed." Wait for the user to say "approved" before attempting ANY file writes.

你阅读计划后输入 approved 开启第一道门。

4. 批准测试后完成实现：

Writ 要求至少包含断言的测试，测试获批后第二道门开启，实现写入才被允许。批准两个门后，Agent 在剩余 safeguard 继续运行的情况下无中断地工作。

5. 使用 writ recall 回溯决策：

writ recall

读取特定变更的决策记录，包括批准的计划、治理规则、变更文件和结果提交。

适用场景

1. 代码实现前的方案审查：Work 模式强制先有计划再有代码，确保每次变更都经过人类审视，而非模型自行判断。
2. 凭证和密钥保护：防止 Agent 在未经确认的情况下向 .env、密钥文件或 SSH 配置写入敏感数据。
3. 跨会话项目记忆：长期项目中途，Claude Code 重启后仍可通过 writ recall 获取历史决策和上下文，无需人工复述。
4. 子 Agent 协作治理：多 Agent 场景下，辅助 Agent 继承主 Agent 的权限边界，无法超出主 Agent 当前时刻的授权范围行动。

适用人群

• 需要在模型外部对 AI 编程助手工作流进行治理的工程师和技术负责人
• 对代码质量有强制流程要求（先计划再实现、先测试再提交）的团队
• 需要跨会话保留项目决策历史的长期项目维护者
• 对凭证和外部数据外泄风险有严格控制要求的企业环境

工作原理

Writ 构建于 Claude Code 的插件机制和本地 Python 运行时之上。Python 层实现强制逻辑（门禁、凭证分类、模式状态机），Docker 运行 Neo4j 图数据库存储规则库、方法论、项目记忆和决策记录。工具执行时，Hook 拦截工具调用，根据当前模式应用相应的治理策略（允许/阻断/确认），Human approval 通过一次性 Secret 机制实现（Secret 只在人类键入特定批准短语时铸造，Agent 无法自我创建）。

混合检索结合 BM25 精确词项和向量语义搜索，通过图关系扩展，并通过 Abstention Gate 在无相关内容时主动弃权而非填充噪声。

官方链接

• PyPI：https://pypi.org/project/claude-writ/
• GitHub：https://github.com/infinri/Writ
• 文档：https://github.com/infinri/Writ/blob/main/docs/install.md