Community写作与编辑github.com

Shaelz/codebase-orient-skill

一个可复用的代码库定向技能,适用于 Claude Code 和 Codex。

codebase-orient-skill 是什么?

该技能旨在帮助 AI 代理(如 Claude Code 和 Codex)快速理解一个不熟悉或复杂的代码仓库,从而在执行非平凡任务前建立必要的上下文。它通过在 `docs/ai/` 目录下创建一个标准化的、带有出处追踪和置信度标签的四件套包,将关于仓库结构、架构、配置和变更的影响面等关键信息进行缓存。技能包含清晰的何时使用、何时跳过的指导原则,以优化令牌消耗,避免代理在重复发现上浪费上下文。同时,它提供了深入发现顺序、特定框架(如 SvelteKit)的探测方法,以及对 CI/CD、深度读取、文件 glob 等方面的精确规则,确保代理的探索是系统、高效且可靠的,输出的地图不会遗漏关键细节。

兼容平台✓Claude Code✓Codex CLI~Cursor
npx skills add Shaelz/codebase-orient-skill

Installed? Explore more 写作与编辑 skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

技能: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 或其他文档,未经独立验证
  • 继承后验证:声明最初来源于文档,随后对照源代码确认
  • 路径存在确认:文件已找到但未读取
  • 部分读取:检查了文件的一部分;可能未捕获全部上下文
  • 完整源代码读取:检查了完整的文件内容
  • 从实现推断:从代码行为方式推断,而非显式说明
  • 从注释/测试/固定装置推断:源自非权威上下文;最多视为强推断
  • 通过测试验证行为:通过测试执行确认
  • 未知:基础未建立;不要作为事实呈现

在最终报告和定向文档中,为每个非平凡声明标记上述来源之一,以便读者判断哪些声明在采取行动前需要重新验证。

发现顺序

自定义说明: 以下发现顺序有意设计的很宽泛,适用于大多数项目形态而无需编辑。您可以为特定项目调整文件路径和顺序,但这是可选的——在首次使用前并非必须。

按此顺序执行:

  1. 项目指令文件,如 CLAUDE.md、AGENTS.md 和 README.md(如果存在)——产品目的、代理规则、项目约定。 文档即假设规则
    • 将这些文档视为有用的假设,而非权威真理。
    • 提取关于架构、路由、部署、测试和真相源文件的高影响事实性声明。
    • 在依赖这些声明之前,对照源代码进行验证。关注会影响未来编辑的声明;不要审计每个句子。
    • 不要将这些文档中的声明复制到 CODEBASE_MAP.md 中,除非标记它们是 从源代码/配置独立验证 还是 继承自现有文档。
    • 如果指令文档与源代码显示的内容相比已过时或具有误导性,则在 OPEN_QUESTIONS.md 中根据隐藏风险报告规则记录偏差,并标记为文档漂移。
    • 映射指令层拓扑:记录存在哪些指令文件(例如 CLAUDE.md、AGENTS.md、.claude/settings.json)及其范围(项目本地 vs 用户级别)。将此记录在 CODEBASE_MAP.md 中;这有助于未来的代理知道哪些规则适用。
  2. 项目清单(例如 package.json、pyproject.toml、Cargo.toml)——依赖、脚本、构建/测试命令
  3. 构建和配置文件(例如框架配置、打包工具配置)——适配器、构建配置
  4. scripts/ 目录(如果存在)——可能包含未在包脚本或 CI 中表示的手动运行工具
  5. 入口点和路由层——所有页面、控制器或 API 路由
  6. 核心业务逻辑——领域类型、模型、评分、报告逻辑
  7. 服务器端服务——认证、数据库/模式、电子邮件、外部集成
  8. UI/展示层——组件、视图、模板
  9. 国际化或复制文件——本地化文件
  10. 请求生命周期/中间件——钩子、拦截器、中间件
  11. 数据库层——迁移、模式快照
  12. 测试——测试结构和覆盖范围形态
  13. 文档——现有文档、验证矩阵。如果找到发布计划、里程碑追踪文档或版本变更日志,则在 CODEBASE_MAP.md 中添加一个 ## 发布状态 部分,总结当前版本、活跃里程碑以及阻止下一个版本发布的内容。如果没有发布生命周期工件,则省略此部分。
  14. 已知的不确定性

特定框架探测

当检测到相关框架时,除通用发现顺序外,还应应用这些探测。

该可复用技能目前包含一组针对 SvelteKit 的显式调谐探测集。其他框架目前使用通用发现顺序,除非后来的实战或评估证据证明需要专门调谐的探测部分。

SvelteKit

当检测到 SvelteKit 项目时,对以下文件模式进行 glob 操作:

  • src/routes/**/+page.svelte:UI 路由页面;每个文件都是一个路由候选;检查子目录,而不仅仅是顶层 src/routes/+page.svelte
  • src/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 廉价地解决存在和范围问题。仅当需要特定文件的内容时才进行有针对性的读取。

(之后的内容被截断,未完全包含在原始输入中)

相关技能