PANYUXIN6/pyx-skills / repo-map-first
repo-map-first
Verified根据源代码证据定位代码归属并判断仓库地图是否可信。适用于归属不明、跨边界行为变更、入口或依赖变更,或地图可能误导代码放置的情况;也适用于明确要求检查、使用、创建或修复地图,以及依赖技能的仓库上下文初始化或验证。
用仓库证据决定变更位置
当放错位置可能跨越职责边界,或让影响扩散到错误层级时,先确定变更属于哪里,再实施。让仓库地图以证据为基础;只有任务或明确请求证明文档工作合理时才更新它。
选择调用模式
明确地图模式
用户点名本技能,或要求创建、修复、更新、检查或使用仓库地图文档时,一律使用此模式。
请求的动作决定范围;点名技能本身不授权修改文档。
- 检查或使用: 阅读相关现有地图,用源代码验证与任务有关的说法,并报告归属、差异和限制。尽可能从源代码补齐缺失信息。地图缺失或过时不会把检查变成创建或修复任务。
- 创建、修复或更新: 检查现有地图和源代码,然后在请求范围内创建缺失文档或修复过时的相关部分。用户要求仓库地图但未点名文档时,同时覆盖
docs/REPO_MAP.md和docs/ARCHITECTURE.md;请求其中一个并不要求创建另一个。准确部分保持不变。 - 在任何依赖实施前完成被请求的地图工作。只要求地图的任务以地图结果和证据结束,不授权代码修改。
当所需的所有者、入口、流程和依赖都可定位且有证据支持,并已说明重要未知项时,地图工作即足够。检查可以报告未解决缺口而不修改文档。创建和修复必须生成所请求的产物,或说明哪些缺失证据阻止了完成。
自动位置风险模式
只有既有仓库的行为变更存在真实位置风险时才使用此模式,例如:
- 从请求和已知上下文仍无法确定职责归属或实现位置;
- 变更跨越模块或层级边界;
- 入口、依赖方向、公开契约或关键调用流程可能改变;
- 仓库陌生且工作并非局部修改;
- 相关地图似乎缺失、过时、矛盾,或不足以支持跨边界决定。
跨多个文件本身不够。职责清晰范围内的局部、规格明确变更不需要本技能。
如果简短检查表明放置位置清晰、没有跨越边界且没有持久结构变更,停止使用本技能,按正常实施流程继续,不做位置分析或创建地图。
自动模式下缺少地图时,先从相关源代码确定位置。只有安全放置所必需,或任务会改变持久仓库结构时,才创建或修复仓库文档。
仓库上下文初始化
只有另一项技能因 docs/REPO_MAP.md 或 docs/ARCHITECTURE.md 缺失而明确需要仓库上下文时,才使用此模式。
- 确定缺失的文档,并保留现有配套文档。
- 阅读适用的仓库规则和已有文档。
- 使用
rg --files、rg和定向阅读检查仓库,定位清单、工作区、入口、相关模块、公开契约、调用方、依赖和测试。 - 保留依赖技能的目标产物。
- 只创建缺失文档,并在每个生成文件开头写入:
---
generated_by: repo-map-first
authority_status: observed
---
- 只包含有仓库证据支持的说法,未知关系标记为未知。
- 仓库证据不足以满足下列最小内容时,报告
INSUFFICIENT_INPUT,不要创建误导性的地图。
REPO_MAP.md 的最小内容:
- 相关顶层目录和模块;
- 每个相关模块的一句话职责;
- 主要入口;
- 关键调用链或流程;
- 作为证据使用的公开契约和测试位置。
ARCHITECTURE.md 的最小内容:
- 观察到的层级或模块边界;
- 观察到的依赖方向;
- 主要控制或数据流程;
- 重要状态或数据的归属;
- 存在时的外部系统和运行边界。
所需文档存在后,把控制权交回依赖技能。生成文档始终只是观察到的上下文,直到用户明确将 authority_status 改为 confirmed。
仓库上下文验证
只有另一项技能因刚完成的前置任务,或仓库证据表明现有 docs/REPO_MAP.md 或 docs/ARCHITECTURE.md 对依赖任务可能过时时,才使用此模式。
- 保留依赖技能的目标产物。
- 阅读现有地图和 仓库地图时效性检查清单。
- 只检查验证相关范围所需的源代码、入口、所有者、依赖、流程和测试。
- 准确的地图部分保持不变。只修复
authority_status: observed文档中已过时的相关说法,并保留其来源信息。 - 不要根据观察到的代码改写未标记或
authority_status: confirmed的契约。报告矛盾;依赖流程需要解决冲突时,返回INSUFFICIENT_INPUT。 - 报告检查的证据、修复的说法和剩余限制,然后把控制权交回依赖技能。
保持这些边界
- 只有职责归属和代码放置已得到实质解决后才开始实施。
- 用相关源代码和当前行为验证过时或矛盾的地图说法。
- 在明确地图模式中,实施前完成被请求的地图工作。
- 复用已有模块、边界和扩展点;只有请求的行为确立了长期职责时才引入新层。
- 重构仅限于请求行为需要的边界修正。说明根因,并做最小且有理由的修正。
- 除非用户明确确认不同的权威状态,否则保留
generated_by和authority_status的来源信息。 - 仓库上下文初始化或验证期间,保持依赖技能的目标产物不变。
位置分析流程
此流程用于位置风险尚未解决的实施。仅地图工作、仓库上下文初始化和验证遵循各自上面的限定流程。
- 阅读适用仓库规则,并检查足够的源代码以定位当前入口、所有者、调用流程和依赖方向。
- 存在时先阅读
docs/REPO_MAP.md的相关部分,再阅读docs/ARCHITECTURE.md。 - 使用 仓库地图时效性检查清单 判断地图是否可信,以及当前调用模式需要什么。
- 使用 代码放置分析准则 作为质量标准而非固定模板,说明放置决定。除非任务跨越多个独立子系统或位置不确定性很高,否则保持简短。
- 在已确定的职责边界内做最小可行修改。
- 实施后使用 仓库地图同步检查清单。职责、文件、入口或流程改变时更新
REPO_MAP.md;层级、依赖或跨系统关系改变时也更新ARCHITECTURE.md。 - 报告职责、入口或关键流程是否改变,以及地图文档是否已同步。
工作原则
- 优先信任仓库证据,而非记忆中的或预期的架构。
- 先发现上下文,再问泛泛的位置问题。
- 只使用安全放置当前变更所需的最少地图细节。
- 明确的用户控制优先于自动路由判断。
- 区分职责边界和文件数量。
- 保持位置分析简洁,并聚焦实施。
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| 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: 196k | Updated | Claude CodeCodex | Verified | Install |