Skip to content

PANYUXIN6/pyx-skills / repo-map-first

repo-map-first

Verified

根据源代码证据定位代码归属并判断仓库地图是否可信。适用于归属不明、跨边界行为变更、入口或依赖变更,或地图可能误导代码放置的情况;也适用于明确要求检查、使用、创建或修复地图,以及依赖技能的仓库上下文初始化或验证。

用仓库证据决定变更位置

当放错位置可能跨越职责边界,或让影响扩散到错误层级时,先确定变更属于哪里,再实施。让仓库地图以证据为基础;只有任务或明确请求证明文档工作合理时才更新它。

选择调用模式

明确地图模式

用户点名本技能,或要求创建、修复、更新、检查或使用仓库地图文档时,一律使用此模式。

请求的动作决定范围;点名技能本身不授权修改文档。

  • 检查或使用: 阅读相关现有地图,用源代码验证与任务有关的说法,并报告归属、差异和限制。尽可能从源代码补齐缺失信息。地图缺失或过时不会把检查变成创建或修复任务。
  • 创建、修复或更新: 检查现有地图和源代码,然后在请求范围内创建缺失文档或修复过时的相关部分。用户要求仓库地图但未点名文档时,同时覆盖 docs/REPO_MAP.md 和 docs/ARCHITECTURE.md;请求其中一个并不要求创建另一个。准确部分保持不变。
  • 在任何依赖实施前完成被请求的地图工作。只要求地图的任务以地图结果和证据结束,不授权代码修改。

当所需的所有者、入口、流程和依赖都可定位且有证据支持,并已说明重要未知项时,地图工作即足够。检查可以报告未解决缺口而不修改文档。创建和修复必须生成所请求的产物,或说明哪些缺失证据阻止了完成。

自动位置风险模式

只有既有仓库的行为变更存在真实位置风险时才使用此模式,例如:

  • 从请求和已知上下文仍无法确定职责归属或实现位置;
  • 变更跨越模块或层级边界;
  • 入口、依赖方向、公开契约或关键调用流程可能改变;
  • 仓库陌生且工作并非局部修改;
  • 相关地图似乎缺失、过时、矛盾,或不足以支持跨边界决定。

跨多个文件本身不够。职责清晰范围内的局部、规格明确变更不需要本技能。

如果简短检查表明放置位置清晰、没有跨越边界且没有持久结构变更,停止使用本技能,按正常实施流程继续,不做位置分析或创建地图。

自动模式下缺少地图时,先从相关源代码确定位置。只有安全放置所必需,或任务会改变持久仓库结构时,才创建或修复仓库文档。

仓库上下文初始化

只有另一项技能因 docs/REPO_MAP.md 或 docs/ARCHITECTURE.md 缺失而明确需要仓库上下文时,才使用此模式。

  1. 确定缺失的文档,并保留现有配套文档。
  2. 阅读适用的仓库规则和已有文档。
  3. 使用 rg --files、rg 和定向阅读检查仓库,定位清单、工作区、入口、相关模块、公开契约、调用方、依赖和测试。
  4. 保留依赖技能的目标产物。
  5. 只创建缺失文档,并在每个生成文件开头写入:
---
generated_by: repo-map-first
authority_status: observed
---
  1. 只包含有仓库证据支持的说法,未知关系标记为未知。
  2. 仓库证据不足以满足下列最小内容时,报告 INSUFFICIENT_INPUT,不要创建误导性的地图。

REPO_MAP.md 的最小内容:

  • 相关顶层目录和模块;
  • 每个相关模块的一句话职责;
  • 主要入口;
  • 关键调用链或流程;
  • 作为证据使用的公开契约和测试位置。

ARCHITECTURE.md 的最小内容:

  • 观察到的层级或模块边界;
  • 观察到的依赖方向;
  • 主要控制或数据流程;
  • 重要状态或数据的归属;
  • 存在时的外部系统和运行边界。

所需文档存在后,把控制权交回依赖技能。生成文档始终只是观察到的上下文,直到用户明确将 authority_status 改为 confirmed。

仓库上下文验证

只有另一项技能因刚完成的前置任务,或仓库证据表明现有 docs/REPO_MAP.md 或 docs/ARCHITECTURE.md 对依赖任务可能过时时,才使用此模式。

  1. 保留依赖技能的目标产物。
  2. 阅读现有地图和 仓库地图时效性检查清单。
  3. 只检查验证相关范围所需的源代码、入口、所有者、依赖、流程和测试。
  4. 准确的地图部分保持不变。只修复 authority_status: observed 文档中已过时的相关说法,并保留其来源信息。
  5. 不要根据观察到的代码改写未标记或 authority_status: confirmed 的契约。报告矛盾;依赖流程需要解决冲突时,返回 INSUFFICIENT_INPUT。
  6. 报告检查的证据、修复的说法和剩余限制,然后把控制权交回依赖技能。

保持这些边界

  • 只有职责归属和代码放置已得到实质解决后才开始实施。
  • 用相关源代码和当前行为验证过时或矛盾的地图说法。
  • 在明确地图模式中,实施前完成被请求的地图工作。
  • 复用已有模块、边界和扩展点;只有请求的行为确立了长期职责时才引入新层。
  • 重构仅限于请求行为需要的边界修正。说明根因,并做最小且有理由的修正。
  • 除非用户明确确认不同的权威状态,否则保留 generated_by 和 authority_status 的来源信息。
  • 仓库上下文初始化或验证期间,保持依赖技能的目标产物不变。

位置分析流程

此流程用于位置风险尚未解决的实施。仅地图工作、仓库上下文初始化和验证遵循各自上面的限定流程。

  1. 阅读适用仓库规则,并检查足够的源代码以定位当前入口、所有者、调用流程和依赖方向。
  2. 存在时先阅读 docs/REPO_MAP.md 的相关部分,再阅读 docs/ARCHITECTURE.md。
  3. 使用 仓库地图时效性检查清单 判断地图是否可信,以及当前调用模式需要什么。
  4. 使用 代码放置分析准则 作为质量标准而非固定模板,说明放置决定。除非任务跨越多个独立子系统或位置不确定性很高,否则保持简短。
  5. 在已确定的职责边界内做最小可行修改。
  6. 实施后使用 仓库地图同步检查清单。职责、文件、入口或流程改变时更新 REPO_MAP.md;层级、依赖或跨系统关系改变时也更新 ARCHITECTURE.md。
  7. 报告职责、入口或关键流程是否改变,以及地图文档是否已同步。

工作原则

  • 优先信任仓库证据,而非记忆中的或预期的架构。
  • 先发现上下文,再问泛泛的位置问题。
  • 只使用安全放置当前变更所需的最少地图细节。
  • 明确的用户控制优先于自动路由判断。
  • 区分职责边界和文件数量。
  • 保持位置分析简洁,并聚焦实施。
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 196kUpdated Claude CodeCodexVerifiedInstall