Pilot Shell /setup-rules 12阶段深度解析：自动为代码库生成AI上下文

Pilot Shell /setup-rules 12阶段深度解析自动为代码库生成AI上下文【免费下载链接】pilot-shellHow real engineers run Claude Code and Codex: spec-driven planning, enforced TDD, persistent memory, and quality enforcement on all levels. Make your agents production-ready.项目地址: https://gitcode.com/GitHub_Trending/cl/pilot-shellPilot Shell的/setup-rules技能是一个开箱即用的项目规则引擎它在终端中自动读取你的代码库生成并审计AGENTS.md、CLAUDE.md与路径级规则让 Claude Code 与 Codex 共享同一份 AI 上下文——无需手动编写、无需担心规则过期。本指南将逐阶段拆解它的 12 步工作流帮你在 5 分钟内理解这套AI 上下文自动生成器如何运作。为什么需要自动生成的 AI 上下文新手使用 AI 编码工具时最常见的痛点是上下文丢失每个新会话都要重新解释项目结构、技术栈和约定规则漂移手写的项目规则随着代码演进逐渐失真双 Agent 不一致CLAUDE.md与AGENTS.md各写各的Claude Code 和 Codex 行为不同/setup-rules的解法是单一事实源 自动同步AGENTS.md作为共享核心CLAUDE.md只保留一行AGENTS.md导入详细规则按文件路径按需加载。整套逻辑定义在 orchestrator.md步骤清单由 manifest.json 编排。12阶段流水线总览阶段文件核心动作1 基准约定01-reference.md确定 slug 前缀、目录结构、单一事实源映射2 读取现状02-read.md盘点现有规则、技能、同步器3 迁移旧资产03-migrate.md为无命名空间文件加{slug}-前缀4 质量审计04-audit.md检查冲突、过期引用、路径作用域缺失5 探索代码库05-explore.md用 Semble 语义搜索理解架构与模式6 对比找差距06-compare.md找出未记录的部落知识7 同步项目规则07-sync-project.md重建AGENTS.md共享核心与路径级规则8 同步 MCP08-sync-mcp.md冒烟测试并文档化用户自配 MCP 服务器9 发现新规则09-discover.md基于真实代码模式起草新规则10 交叉核验10-cross-check.md校验实体索引、引用有效性、规则路由一致性11 跨 Agent 同步11-sync-agents.md安装同步器与 CI 漂移检查12 总结报告12-summary.md输出结构化执行报告阶段 1-3先读后写安全迁移阶段 1基准约定确立三条铁律先读后写、简洁至上每个词都消耗 token、幂等执行。它会从 git 仓库名推导项目 slug所有生成的规则统一使用{slug}-前缀避免多仓库共享配置时命名冲突。阶段 2读取现状做全量盘点遍历.claude/rules/下所有规则、CLAUDE.md/AGENTS.md、技能目录并检测三类问题——无命名空间的遗留文件、嵌套规则目录、缺失paths作用域的规则。阶段 3条件迁移只有发现遗留文件才触发。它会询问你选择全部迁移、逐个审查还是跳过把仓库级指导并入AGENTS.md路径级规则重命名为{slug}-project.md等并补上paths前置元数据。阶段 4-6审计与探索让规则可信阶段 4质量审计是最较真的一步内置 15 项检查表冲突检测两个文件一个说用 tab一个说用空格直接标记为 Error过期引用规则里提到的文件/命令已不存在用ls逐一验证上下文膨胀超过 200 行的文件会被警告含糊指令写干净的代码这类空话会被要求给出可验证的标准阶段 5探索代码库如果安装了 Semble它会用语义搜索回答应用如何组织模块鉴权如何处理这类问题未安装则回退到 Grep 直接读文件。所有权威文档ARCHITECTURE.md、CONTRIBUTING.md会保持打开状态作为生成规则的事实来源。阶段 6对比差距把阶段 2 的现状与阶段 5 的发现对照列出未记录的新约定并让你确认更新范围。阶段 7-9生成共享核心与精准规则阶段 7同步项目规则是整个技能的心脏。它把每条现有指令分类到唯一归宿内容类型存放位置仓库级命令、约定、安全边界AGENTS.md控制在 400 行内与特定文件路径绑定的细节.claude/rules/{slug}-{topic}.mdpaths元数据可复用的按需工作流.agents/skills/{slug}-{name}/个人偏好CLAUDE.local.md关键设计AGENTS.md内置一个匹配规则索引列出每条路径级规则的 glob 和作用描述——Claude Code 自动加载规则Codex 则通过索引按需读取实现零重复的双 Agent 一致体验。遇到内容冲突时它会展示原文让你裁决绝不静默合并。阶段 8MCP 同步解析.mcp.json对每个用户自配服务器做只读冒烟测试✅ 已连接 / ⚠️ 部分可用 / ❌ 不可达然后写入文档。注意它刻意不枚举具体工具——MCP 工具自带描述重复列举只会浪费上下文 token。阶段 9发现新规则按出现频率、独特性、易错程度排序候选区域起草规则时严格遵循固定格式名称 → 适用时机 → 模式附代码示例→ 为什么 → 常见错误 → 好坏示例对照。阶段 10-12核验、同步、交付阶段 10交叉核验在安装镜像前做最后一道防线建立实体索引、逐字核对生成内容与源文档的拼写、验证所有交叉引用存在、确认每条详细规则都有非空paths作用域。阶段 11跨 Agent 同步安装确定性检查器 sync-agent-assets.mjs它支持三种模式--install将脚本写入仓库并做首次收敛--write手动恢复镜像--check只读校验可直接接入 CI 作为漂移门禁最终仓库契约被固化为CLAUDE.md内容恰好等于AGENTS.md.agents/skills/是用户可编辑的规范源.claude/skills/是由钩子自动生成的镜像禁止手改。阶段 12总结输出结构化报告目录结构、审计修复项、规则增改数量、作用域验证结果、钩子覆盖状态、检查器--check的精确输出——并引导你到控制台 Share 面板分享成果。快速上手如何运行 /setup-rules安装 Pilot Shell支持 macOS / Linux / Windows WSL2进入你的项目目录在 Claude Code 中输入/setup-rules按结构化问卷回答少量决策问题如是否迁移遗留规则等待 12 阶段跑完审查最终报告技能源码入口orchestrator.md · 步骤明细steps/ · 同步器测试sync-agent-assets.test.mjs小贴士把scripts/sync-agent-assets.mjs --check加入 CI 后任何团队成员手改生成的镜像文件都会让流水线变红——这是让 AI 上下文永远新鲜的关键一步。常见问题FAQ问重复运行 /setup-rules 会破坏已有规则吗答不会。阶段 1 明确幂等原则阶段 4 只提出建议、修改前必须经你确认阶段 7/11 有显式决策门个人未跟踪的本地技能始终被保留。问没有 Semble 能用吗答可以。阶段 5 自动检测未安装时回退到 Grep 直接读文件流程照常完成。问它和我手写 CLAUDE.md 有什么区别答手写规则只有 Claude Code 可见且无审计、无同步、无 CI 门禁/setup-rules生成的是双 Agent 共享、按路径精准加载、漂移可检测的完整体系。【免费下载链接】pilot-shellHow real engineers run Claude Code and Codex: spec-driven planning, enforced TDD, persistent memory, and quality enforcement on all levels. Make your agents production-ready.项目地址: https://gitcode.com/GitHub_Trending/cl/pilot-shell创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考