技能:codebase-orient
目的
在开始非平凡工作之前,让 Claude 了解当前仓库的状态。它会在 docs/ai/ 中创建或协调一个固定的、带有出处追踪的四件套包。源代码和项目配置仍然是权威依据。
何时使用此技能
使用此技能的场景
- 进入一个新的或不熟悉的仓库
- 离开仓库较长时间后,开始一个新的会话
- 在广泛的或多文件的实现工作之前
- 在重构、清理、架构规划或代理交接之前
- 在结构性更改之后:路由、模式、认证、部署、配置或管理界面
- 当
docs/ai/缺失、过时、不完整或内部不一致时 - 当仓库结构、变更面、部署目标、认证行为、管理路由、命令或测试形态不明确时
- 当代理否则会花费大量上下文来重新发现
docs/ai/中已有的或附近的内容时 - 只要用户说“扫描”、“定向”、“理解”、“映射”、“审查”、“审计”、“调查”、“熟悉”或“在我开始之前”时
跳过此技能的场景
- 进行一个微小的、本地的、已知的单个文件编辑
- 修复一个单文件错误,且相关文件和更改已经明确
- 进行仅复制或仅字符串的更改
- 任务紧密限定在已在当前上下文中验证过的文件
docs/ai/刚刚刷新,且任务的范围足够窄,无需完整的定向流程
令牌感知使用指南
docs/ai/ 是一个定向缓存。一个新的缓存能减少跨会话和代理交接的重复仓库发现令牌成本。
- 如果
docs/ai/是最新且完整的:将其作为上下文读取并继续。跳过重新运行定向。 - 如果
docs/ai/可能已过时或缺失:运行技能以刷新缓存。前置的令牌成本会在后续工作中摊销。 - 如果任务很小且目标文件已知:跳过定向。使用有针对性的读取。
- 如果代理会花费大量令牌来重新发现
docs/ai/已经捕获的内容:刷新它。
不要为了节省令牌而跳过定向,然后去猜测结构。如果广泛的仓库发现本应重复或昂贵,则刷新缓存。
定向期间的硬性规则
- 不要修改应用程序或源代码。
- 不要重构。
- 不要提交。
- 在写入之前,对照源代码验证声明。
- 为每个有意义的声明标记置信度标签。
正常模式与试运行模式
正常模式(默认——当用户未指定时使用):
- 通过读取源文件自动解决小的与任务相关的不确定性
- 在干净的仓库中首次使用时创建完整包
- 重用完全匹配当前状态的干净包,而不重写它
- 将不具体的刷新或协调请求视为完全协调
- 在最后报告更改了什么
试运行/仅报告模式(当用户说“试运行”、“仅报告”、“不要写入”、“先提出更改”、“仅审计”、“不写入”或类似内容时使用):
- 检查并收集建议的更改
- 报告对
docs/ai/的建议编辑,但不写入 - 在写入前等待明确批准
如果未指定模式,则默认为正常模式。
生命周期与写入安全
- 显式刷新: 仅当用户明确要求时,才对找到的完全匹配当前状态的包进行刷新或协调。
- 范围限定刷新: 遵循明确的用户范围及其直接依赖项。记录范围限定的覆盖范围,但不推进或声称包范围的完整快照。在完整包存在之前,不要创建部分支持的包。
- 遗留采用: 没有
ORIENTATION_STATE.json的 Markdown 工件属于遗留材料。检查它们,但在写入清单或更改它们之前,需获得明确批准。批准后,从源代码进行协调。 - 脏树: 在写入代表未提交工作的状态之前,询问是否写入脏快照或仅报告。记录树的状况;保持标记为脏状态,直到干净的刷新替换它。
- 没有可用的 Git 历史: 执行完全协调,并记录修订比较不可用。
- 手动编辑: Orient 拥有该包。不要承诺对手动编辑的 Orient 状态进行合并或保留。
置信度标签
- 事实:已在代码或文档中直接验证
- 强推断:由多个文件支持
- 弱推断:有道理但未确认
- 未知:需要更多检查才能编辑
区分声明的建立方式:
- 从源代码/配置独立验证:声明已对照实际源代码或配置文件检查,而非取自文档
- 继承自现有文档:声明取自 CLAUDE.md、README 或其他文档,未经独立验证
- 继承后验证:声明最初来源于文档,随后对照源代码确认
- 路径存在确认:文件已找到但未读取
- 部分读取:检查了文件的一部分;可能未捕获全部上下文
- 完整源代码读取:检查了完整的文件内容
- 从实现推断:从代码行为方式推断,而非显式说明
- 从注释/测试/固定装置推断:源自非权威上下文;最多视为强推断
- 通过测试验证行为:通过测试执行确认
- 未知:基础未建立;不要作为事实呈现
在最终报告和定向文档中,为每个非平凡声明标记上述来源之一,以便读者判断哪些声明在采取行动前需要重新验证。
发现顺序
自定义说明: 以下发现顺序有意设计的很宽泛,适用于大多数项目形态而无需编辑。您可以为特定项目调整文件路径和顺序,但这是可选的——在首次使用前并非必须。
按此顺序执行:
- 项目指令文件,如
CLAUDE.md、AGENTS.md和README.md(如果存在)——产品目的、代理规则、项目约定。 文档即假设规则- 将这些文档视为有用的假设,而非权威真理。
- 提取关于架构、路由、部署、测试和真相源文件的高影响事实性声明。
- 在依赖这些声明之前,对照源代码进行验证。关注会影响未来编辑的声明;不要审计每个句子。
- 不要将这些文档中的声明复制到
CODEBASE_MAP.md中,除非标记它们是 从源代码/配置独立验证 还是 继承自现有文档。 - 如果指令文档与源代码显示的内容相比已过时或具有误导性,则在
OPEN_QUESTIONS.md中根据隐藏风险报告规则记录偏差,并标记为文档漂移。 - 映射指令层拓扑:记录存在哪些指令文件(例如
CLAUDE.md、AGENTS.md、.claude/settings.json)及其范围(项目本地 vs 用户级别)。将此记录在CODEBASE_MAP.md中;这有助于未来的代理知道哪些规则适用。
- 项目清单(例如
package.json、pyproject.toml、Cargo.toml)——依赖、脚本、构建/测试命令 - 构建和配置文件(例如框架配置、打包工具配置)——适配器、构建配置
scripts/目录(如果存在)——可能包含未在包脚本或 CI 中表示的手动运行工具- 入口点和路由层——所有页面、控制器或 API 路由
- 核心业务逻辑——领域类型、模型、评分、报告逻辑
- 服务器端服务——认证、数据库/模式、电子邮件、外部集成
- UI/展示层——组件、视图、模板
- 国际化或复制文件——本地化文件
- 请求生命周期/中间件——钩子、拦截器、中间件
- 数据库层——迁移、模式快照
- 测试——测试结构和覆盖范围形态
- 文档——现有文档、验证矩阵。如果找到发布计划、里程碑追踪文档或版本变更日志,则在
CODEBASE_MAP.md中添加一个## 发布状态部分,总结当前版本、活跃里程碑以及阻止下一个版本发布的内容。如果没有发布生命周期工件,则省略此部分。 - 已知的不确定性
特定框架探测
当检测到相关框架时,除通用发现顺序外,还应应用这些探测。
该可复用技能目前包含一组针对 SvelteKit 的显式调谐探测集。其他框架目前使用通用发现顺序,除非后来的实战或评估证据证明需要专门调谐的探测部分。
SvelteKit
当检测到 SvelteKit 项目时,对以下文件模式进行 glob 操作:
src/routes/**/+page.svelte:UI 路由页面;每个文件都是一个路由候选;检查子目录,而不仅仅是顶层src/routes/+page.sveltesrc/routes/**/+page.server.ts:服务器端数据加载、表单动作和路由级别访问控制src/routes/**/+layout.svelte:共享布局外壳src/routes/**/+layout.server.ts:用于布局级别认证、会话或数据的服务器端加载函数src/routes/**/+server.ts:API 端点和仅限服务器的请求处理程序
服务器端路由文件(+page.server.ts、+layout.server.ts、+server.ts)对于理解认证、数据加载、表单动作、API 端点和路由级别访问控制至关重要。在映射路由或变更面时,不要跳过它们。
- 标准应用外壳模板是
src/app.html。 svelte.config.js中的适配器选择决定了部署目标——在做出与部署相关的声明之前进行确认。
CI/部署精度规则
在读取 CI 或部署工作流文件时,保留操作上相关的细节。不要将具体细节简化成模糊的摘要。
捕获并报告:
- 并发组名称(哪些运行相互竞争)
cancel-in-progress行为——如果为true,请说“较新的运行会取消同一组中正在进行的运行”,而不仅仅是“防止并行部署”fail-fast行为- 部署工件路径
- 发布命名格式,包括任何时间戳或哈希组件
- 旧版本或工件的保留和清理策略
- 手动 vs 自动触发条件
- 所需的秘密和环境变量
- 部署是就地覆盖、暂存到临时路径、使用符号链接,还是使用版本化发布目录
当直接从工作流文件读取时,将 CI/部署声明标记为 从源代码/配置独立验证。不要以丢失操作员在事件中需要的精度的方式总结这些细节。
读取深度启发式
默认情况下,不要读取每个大型的 CSS、配置或生成文件。
- 完整读取:直接影响请求任务的(入口点、路由、认证、模式、构建配置、要编辑的文件)文件。
- 部分读取或仅路径确认:次要表面,如大型样式表、供应商代码、生成的输出,或与任务无关的配置文件。如果您仅确认文件路径或读取了部分内容,请在报告中明确说明,使用置信度标签下定义的 路径存在确认 或部分读取标签。
- 跳过:明显超出范围的文件(例如二进制资源、锁文件、测试快照),除非特定问题使其相关。
如有疑问,首选先确认存在,仅在声明需要时才完整读取。
路径存在 vs 内容读取
对于低风险的清单声明——确认目录结构、列出文件计数或注意到配置文件存在——路径存在就足够了。
当声明影响行为、架构、风险、命令、部署、认证、路由或变更面时,请读取实际文件内容。不要仅基于路径存在就将声明标记为 从源代码/配置独立验证,如果文件易于检查且其内容将严重影响地图。
小型真相源文件读取规则
如果一个小的文件似乎定义了项目中使用到的词汇或真相源令牌,请读取足够多的内容以验证词汇,而不是从文档中继承词汇。
适用此规则的示例:
- CSS 自定义属性令牌文件
- 路由或菜单配置文件
- 小型模式或常量文件
- 命令或插件注册表
当充足时,使用部分读取。使用适当的声明来源标记结果声明(部分读取、完整源代码读取)。如果您实际上没有读取该文件,请不要将其标记为 从源代码/配置独立验证。
廉价工件 Glob 规则
在留下关于静态资源、脚本、生成输出、文档、测试、迁移或配置文件的存在或范围的未解决问题之前,使用廉价的路径 glob 来解决它。
可以尝试的常见 glob 模式:
static/**/*public/**/*scripts/**/*tests/**/*或test/**/*或spec/**/*.github/workflows/*docs/**/*migrations/**/*dist/**/*或build/**/*
默认情况下,不要深度读取所有匹配的文件。使用 glob 廉价地解决存在和范围问题。仅当需要特定文件的内容时才进行有针对性的读取。
(之后的内容被截断,未完全包含在原始输入中)