WISC 框架实战：为 AI 编码助手编写 CLI 模块规则文件 —— Archon `cli.md` 全解析

文档教程提示工程人工智能【免费下载链接】context-engineering-introContext engineering is the new vibe coding - its the way to actually make AI coding assistants work. Claude Code is the best for this so thats what this repo is centered around, but you can apply this strategy with any AI coding assistant!项目地址https://gitcode.com/gh_mirrors/co/context-engineering-intro点击查看免费下载本篇技术指南以 WISC 上下文工程框架Write / Isolate / Select / Compress中的 Tier-2 按需规则文件为切入点完整剖析.claude/rules-example/cli.md这份针对 Archon CLI 模块的工程约定文档覆盖 CLI 命令面、启动行为、参数类型约束、Git 与隔离体系绑定、端口分配、适配器设计与反模式清单。读完本文你将掌握如何为自己的 CLI 子模块编写一份可被 Claude Code 自动加载、可被 AI Agent 准确执行的高质量规则文件并理解规则背后对应的源码级工程决策。规则文件在 WISC 上下文体系中的定位WISC 是围绕 AI 编码上下文管理提出的四策略框架Write把 Agent 的记忆外置到文件、Isolate用子 Agent 隔离研究噪声、Select只加载当前任务需要的上下文、Compress会话过长时压缩或交接其整体思路记录在 use-cases/ai-coding-wisc-framework/README.md 中。该框架用一套三层渐进式上下文系统落地Tier 1全局规则CLAUDE.md——始终加载覆盖项目结构、常用命令、架构概览要求精简建议 500 行以内Tier 2按需规则.claude/rules/——依据 Agent 正在触碰的文件路径自动加载每个规则文件通过paths:frontmatter 声明触发条件Tier 3参考文档.claude/docs/——不自动加载由子 Agent 先读头部判断相关性按需全文读取。cli.md属于Tier 2 按需规则。按 README 中的映射表它对应的触发路径是**/cli/**覆盖内容是「CLI 适配器、命令注册、输出格式」。也就是说当 Agent 开始编辑项目中任何与 CLI 相关的文件时Claude Code 会自动把这份规则注入上下文让 Agent 在写代码之前就清楚该模块的全部约定——这正是Select策略的落地方式不是把整个项目的约定全部塞进CLAUDE.md而是按需精准投放。与其并列的还有testing.md、web-frontend.md、database.md、orchestrator.md、workflows.md、adapters.md、isolation.md、server-api.md等规则文件它们共同组成一套「按路径作用域分发的工程规范」体系。规则文件解剖cli.md 的骨架与信息组织cli.md全文结构清晰遵循「先声明触发条件再按主题分节」的写法--- paths: - packages/cli/**/*.ts --- # CLI Conventions ## Commands ## Startup Behavior ## WorkflowRunOptions Discriminated Union ## Git Repo Requirement ## Conversation ID Format ## Port Allocation ## CLIAdapter ## Architecture ## Anti-patterns每个 H2 小节只解决一个具体问题且都给出可直接执行的命令、可照抄的类型定义或可验证的路径说明。这种「一个规则文件 一个模块的完整作战手册」的粒度正是 WISC 框架推荐的规则组织方式与同目录下adapters.md认证、懒加载日志、消息切分、isolation.md品牌化类型、7 步解析、错误分类、workflows.md三种执行模式、变量替换、依赖注入相互独立、互不重叠Agent 按触碰路径只加载需要的部分。CLI 命令面四条命令族完整解读cli.md首先给出 CLI 的完整命令清单全部以bun run cli为入口分为四族1. Workflow 命令要求 git 仓库bun run cli workflow list [--json] bun run cli workflow run name [message] [--branch branch] [--from-branch base] [--no-worktree] [--resume] bun run cli workflow status [runId]workflow list列出可用工作流--json输出结构化结果便于脚本消费workflow run按名称运行工作流message作为工作流输入参数--branch指定目标分支--from-branch指定基于哪个分支创建--no-worktree与--resume属于隔离相关的开关见下文判别联合workflow status查询运行状态可选runId精确到某次运行。2. Isolation 命令隔离与清理bun run cli isolation list bun run cli isolation cleanup [days] # default: 7 days bun run cli isolation cleanup --merged # removes merged branches remote refs bun run cli complete branch-name [--force] # full lifecycle: worktree local/remote branchesisolation list列出当前所有隔离环境worktreeisolation cleanup清理超过 N 天的环境默认 7 天--merged变体只移除已合并进主分支的分支并同步删除远端引用remote refscomplete执行「完整生命周期」收尾——同时清理 worktree、本地分支与远端分支--force会跳过未提交变更检查属于高风险开关见反模式。注意这里的「默认 7 天」与 Tier-3 文档 isolation-and-worktree-guide.md 中描述的服务器端陈旧环境阈值默认 14 天STALE_THRESHOLD_DAYS是两个不同的数字CLI 的cleanup是用户主动触发的手动清理7 天服务器端runScheduledCleanup()是启动时 每 6 小时一次的定时清理14 天。两条路径共享removeEnvironment()的同一套安全检查文件系统消失即移除、分支已合并进主分支才移除、陈旧且未被其他会话引用才移除。3. 交互命令bun run cli chat [--cwd path]以交互模式启动 CLI 会话--cwd指定工作目录。chat是唯一进入「对话循环」的入口其余命令均为一次性执行。4. 设置命令bun run cli setup bun run cli versionsetup负责首次环境配置创建~/.archon目录、环境文件等version输出 CLI 版本号。启动行为四步初始化顺序规则文件明确规定了 CLI 进程启动时的严格顺序这是防止环境污染与认证错配的关键删除process.env.DATABASE_URL——防止目标仓库的数据库配置泄漏进 CLI 进程。因为 CLI 通常运行在被操作的仓库目录里若该仓库自带.env或其他环境注入DATABASE_URL可能被无意继承以override: true加载~/.archon/.env——用户级配置强制覆盖已存在的同名变量确保 CLI 使用 Archon 自身的数据库连接智能 Claude 认证兜底——如果环境里既没有CLAUDE_API_KEY也没有CLAUDE_CODE_OAUTH_TOKEN则自动设置CLAUDE_USE_GLOBAL_AUTHtrue复用 Claude Code 全局登录态避免用户因未配置密钥而无法使用在 dotenv 配置完成之后才 import 所有命令——命令模块可能在模块级读取环境变量因此加载顺序必须晚于环境初始化否则会出现「读到空配置」的竞态问题。这四步与 README 的架构说明 相互印证CLI 与 Web UI 共用同一套~/.archon数据目录环境文件就是两者共享配置的载体。WorkflowRunOptions用判别联合类型约束 CLI 参数规则文件给出了一个关键的类型设计——WorkflowRunOptions判别联合Discriminated Uniontype WorkflowRunOptions | { branchName?: undefined; noWorktree?: undefined; resume?: boolean } // No isolation | { branchName: string; fromBranch?: string; noWorktree?: boolean; resume?: undefined }; // With branch这个类型把「是否启用隔离」编码进类型系统本身形态一无隔离branchName与noWorktree均为undefinedresume可选为boolean形态二有分支隔离branchName必须为stringfromBranch可选resume必须为undefined。由此派生出三条命令行规则--branch feature-auth→ 为feature-auth分支创建或复用一个 worktree隔离环境--no-worktree→ 不建 worktree直接在分支上检出工作只能与--branch组合--resume→ 恢复本会话上一次的运行与--branch互斥。从 isolation-and-worktree-guide.md 可以推断其底层原理--branch走的是IsolationResolver的 7 步解析现有环境引用 → 无代码库跳过 → 工作流复用 → 关联 issue 共享 → PR 分支收养 → 数量上限检查自动清理 → 新建环境而--resume复用「同一 codebase workflowType workflowId 复用活跃环境」的规则。把互斥关系写进类型比在运行时抛错更早地拦截了非法参数组合——这正是「用类型约束工具行为」的工程实践。与 Git 和隔离体系的深度绑定规则文件强调workflow 与 isolation 命令必须在 git 仓库内运行。CLI 会把当前工作目录CWD解析到 git 仓库根目录调用git rev-parse --show-toplevel定位根目录——因此在仓库的任意子目录执行都有效。这是一条可验证的硬性前置条件反模式部分也再次强调不在 git 仓库内运行 workflow/isolation 命令必然失败。complete branch-name的「完整生命周期」语义与 isolation.md 的销毁流程 一一对应git worktree remove [--force]移除工作树 → 若目录残留存在未跟踪文件则清理目录 →git branch -D删除本地分支 →--force之外还会git push origin --delete删除远端分支。其中hasUncommittedChanges()采用保守策略遇到意外错误时返回true宁可阻止删除也不冒险丢失数据这正是--force需要「真正安全才使用」的原因。Conversation ID 与端口分配会话 ID 格式CLI 生成会话 ID 的规则是cli-{timestamp}-{random6}例如cli-1703123456789-a7f3bc。前缀cli使同一套会话管理逻辑下能清晰区分来源对比 adapters.md 中 Slack 的channel:thread_ts、Telegram 的数字 chat ID、GitHub 的owner/repo#numbertimestamp 提供排序能力6 位随机后缀避免并发冲突。端口分配worktree 感知的确定性算法规则文件指出 CLI 与服务器共享同一套基于哈希的端口分配算法范围固定为3190–4089。其完整实现细节见 isolation-and-worktree-guide.md 的 port-allocation 章节若设置了PORT环境变量 → 直接使用若 CWD 位于 worktree 内 → 计算MD5(cwd)取readUInt16BE(0) % 900 100作为偏移量最终端口 3090 offset即 3190–4089若不在 worktree 内 → 固定使用3090。这套算法的关键特性是确定性同一 worktree 路径永远得到同一端口因此在 worktree 内运行bun dev可自动分配到唯一端口且多次重启端口不变避免了并行开发时端口冲突——这是「CLI 与隔离体系深度耦合」的又一例证。CLIAdapter平台适配器的本地实现CLIAdapter是 Archon 平台抽象层的本地实现。规则文件给出其核心契约实现IPlatformAdapter——与 Slack、Telegram、GitHub、Discord、Web 适配器实现同一接口见 adapters.md因此 CLI 天然复用整个消息处理管线流式输出到 stdout——适配器的sendMessage把内容输出到标准输出getStreamingMode()默认返回batch——可通过构造函数选项配置。这与 architecture-deep-dive.md 中「Slack 返回batch、Web 返回stream」的平台差异化设计一致CLI 是脚本化的非交互工具批次模式更合适无需认证——CLI 仅在本地运行天然可信这是它与所有远程适配器的本质区别远程适配器必须在onMessage()之前做授权检查。可以推断CLI 会话的消息处理同样遵循「fire-and-forget」模式适配器调用void this.messageHandler(event)错误由上层orchestrator/锁管理器处理而不是在适配器内抛错——这是 adapters.md 反模式 中「Never throw fromonMessagehandlers」的直接体现。架构与依赖CLI 在 Archon 中的位置规则文件的 Architecture 一节给出 CLI 的依赖关系与数据流依赖关系archon/cli依赖archon/core、archon/workflows、archon/git、archon/isolation、archon/paths五个包。这符合 README 的架构描述paths零依赖 →git只依赖paths→isolation依赖git paths→workflows依赖git pathscore是汇聚层工作流依赖注入CLI 通过createWorkflowDeps()来自archon/core/workflows/store-adapter构建工作流执行所需的依赖。结合 workflows.md 的WorkflowDeps接口 可知执行器需要store: IWorkflowStore数据库抽象、getAssistantClient返回 claude 或 codex 客户端、loadConfig加载配置三要素全部通过注入获得archon/workflows对archon/core保持零依赖数据库共享CLI 与服务器共用同一个~/.archon/archon.db或DATABASE_URL指定的数据库会话生命周期create → run workflow → persist messages——与 Web UI 完全相同的流程因此在 CLI 中发起的会话在 Web 界面同样可见、可续。反模式清单四条红线规则文件以「Never」句式列出四条反模式作为 Agent 的行为禁区绝不在 git 仓库外运行 CLI 命令——workflow/isolation 命令依赖git rev-parse --show-toplevel解析仓库根脱离仓库必然失败绝不在~/.archon/.env中把DATABASE_URL指向目标应用的数据库——CLI 启动时会以override: true加载该文件一旦指向目标应用的库CLI 的读写就会污染应用数据同理启动第一步主动删除进程环境中的DATABASE_URL正是为了防止反方向目标仓库环境 → CLI的泄漏绝不在分支并非真正安全可删时使用complete --force——--force跳过未提交变更检查而hasUncommittedChanges()本身是保守的意外错误也返回 true绕过它等于放弃最后一道数据安全闸门绝不在 CLI 命令中加入交互式提示——CLI 是非交互工具所有选项必须通过 flags 传递。这条约束保证了 CLI 可被脚本、CI 和 Agent 无人工干预地调用。这四条「Never」与adapters.md、isolation.md、workflows.md中的反模式清单风格一致共同构成了 Archon 的「可执行工程规范」它们不是建议而是Agent 在生成代码时必须遵守的硬约束。如何为自己的项目编写同类规则文件从cli.md可以提炼出一套可复制的「CLI/子模块规则文件写作模板」用paths:frontmatter 划定作用域——写packages/cli/**/*.ts这样精确的 glob让规则只在 Agent 触碰 CLI 代码时加载保持CLAUDE.md精简对应 README 的「Keep it lean」原则命令即文档——把所有命令、参数、默认值完整列出并注释默认值如cleanup [days] # default: 7 days让 Agent 无需查源码就能正确调用写出启动顺序与初始化副作用——环境变量删除、配置文件加载、认证兜底这些「看不见的坑」必须显式写出来否则 Agent 很可能写出依赖错误状态的代码用类型/接口定义替代口头描述——WorkflowRunOptions判别联合直接给出合法形态Agent 可以从类型反推参数约束列清硬性前置条件——「必须在 git 仓库内运行」这类约束要写进规则并配一句原因git rev-parse --show-toplevel反模式清单用 Never 句式——把最容易犯的错误逐条列出Agent 在代码生成阶段就会主动规避。结语cli.md表面上是 Archon 项目的一份 CLI 约定文档实质上展示了 WISC 框架「Select」策略的完整落地形态一个路径作用域化的规则文件把命令面、启动顺序、类型约束、Git 集成、端口算法、适配器契约和反模式浓缩为 Agent 可自动加载、可严格执行的上下文。它同时体现了 Write 的思想——这些约定被外置成文件跨会话、跨 Agent 持久有效。参考同目录的adapters.md、isolation.md、workflows.md以及 Tier-3 的architecture-deep-dive.md、isolation-and-worktree-guide.md可以进一步观察这套「规则 参考文档」双层的上下文工程方法论如何在真实项目中自洽运转。赞分享文档教程提示工程人工智能【免费下载链接】context-engineering-introContext engineering is the new vibe coding - its the way to actually make AI coding assistants work. Claude Code is the best for this so thats what this repo is centered around, but you can apply this strategy with any AI coding assistant!项目地址https://gitcode.com/gh_mirrors/co/context-engineering-intro点击查看免费下载相关推荐WISC 框架 /prime-isolation 命令实战为 AI 编码代理定向注入 Git Worktree 隔离系统上下文WISC 框架 /prime isolation 命令实战为 AI 编码代理定向注入 Git Worktree 隔离系统上下文 /prime isolatio文档教程提示工程人工智能Claude Code CLI 工具 run-skill 编写指南以 run-skill-generator 的 cli.md 为模板Claude Code CLI 工具 run skill 编写指南以 run skill generator 的 cli.md 为模板 这篇指南围绕仓库中收录文档知识库WISC 框架实战用 /commit 命令为 AI 编码工作流构建“可追溯的 git 长期记忆”WISC 框架实战用 /commit 命令为 AI 编码工作流构建“可追溯的 git 长期记忆” 导读 在 AI 编码助手参与开发的场景中代码提交不仅是版本文档教程提示工程人工智能创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考