PANYUXIN6/pyx-skills / repo-map-first
repo-map-first
Verified根据源代码证据定位代码归属并判断仓库地图是否可信。适用于归属不明、跨边界行为变更、入口或依赖变更,或地图可能误导代码放置的情况;也适用于明确要求检查、使用、创建或修复地图,以及依赖技能的仓库上下文初始化或验证。
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 7.1 KB |
| references/map-sync-checklist.md | markdown | 1.6 KB |
| references/placement-analysis.md | markdown | 1.1 KB |
| references/staleness-checklist.md | markdown | 1.9 KB |
SKILL.md
View on GitHub---
name: repo-map-first
description: 根据源代码证据定位代码归属并判断仓库地图是否可信。适用于归属不明、跨边界行为变更、入口或依赖变更,或地图可能误导代码放置的情况;也适用于明确要求检查、使用、创建或修复地图,以及依赖技能的仓库上下文初始化或验证。
license: MIT
---
# 用仓库证据决定变更位置
当放错位置可能跨越职责边界,或让影响扩散到错误层级时,先确定变更属于哪里,再实施。让仓库地图以证据为基础;只有任务或明确请求证明文档工作合理时才更新它。
## 选择调用模式
### 明确地图模式
用户点名本技能,或要求创建、修复、更新、检查或使用仓库地图文档时,一律使用此模式。
请求的动作决定范围;点名技能本身不授权修改文档。
- **检查或使用:** 阅读相关现有地图,用源代码验证与任务有关的说法,并报告归属、差异和限制。尽可能从源代码补齐缺失信息。地图缺失或过时不会把检查变成创建或修复任务。
- **创建、修复或更新:** 检查现有地图和源代码,然后在请求范围内创建缺失文档或修复过时的相关部分。用户要求仓库地图但未点名文档时,同时覆盖 `docs/REPO_MAP.md` 和 `docs/ARCHITECTURE.md`;请求其中一个并不要求创建另一个。准确部分保持不变。
- 在任何依赖实施前完成被请求的地图工作。只要求地图的任务以地图结果和证据结束,不授权代码修改。
当所需的所有者、入口、流程和依赖都可定位且有证据支持,并已说明重要未知项时,地图工作即足够。检查可以报告未解决缺口而不修改文档。创建和修复必须生成所请求的产物,或说明哪些缺失证据阻止了完成。
### 自动位置风险模式
只有既有仓库的行为变更存在真实位置风险时才使用此模式,例如:
- 从请求和已知上下文仍无法确定职责归属或实现位置;
- 变更跨越模块或层级边界;
- 入口、依赖方向、公开契约或关键调用流程可能改变;
- 仓库陌生且工作并非局部修改;
- 相关地图似乎缺失、过时、矛盾,或不足以支持跨边界决定。
跨多个文件本身不够。职责清晰范围内的局部、规格明确变更不需要本技能。
如果简短检查表明放置位置清晰、没有跨越边界且没有持久结构变更,停止使用本技能,按正常实施流程继续,不做位置分析或创建地图。
自动模式下缺少地图时,先从相关源代码确定位置。只有安全放置所必需,或任务会改变持久仓库结构时,才创建或修复仓库文档。
### 仓库上下文初始化
只有另一项技能因 `docs/REPO_MAP.md` 或 `docs/ARCHITECTURE.md` 缺失而明确需要仓库上下文时,才使用此模式。
1. 确定缺失的文档,并保留现有配套文档。
2. 阅读适用的仓库规则和已有文档。
3. 使用 `rg --files`、`rg` 和定向阅读检查仓库,定位清单、工作区、入口、相关模块、公开契约、调用方、依赖和测试。
4. 保留依赖技能的目标产物。
5. 只创建缺失文档,并在每个生成文件开头写入:
```yaml
---
generated_by: repo-map-first
authority_status: observed
---
```
6. 只包含有仓库证据支持的说法,未知关系标记为未知。
7. 仓库证据不足以满足下列最小内容时,报告 `INSUFFICIENT_INPUT`,不要创建误导性的地图。
`REPO_MAP.md` 的最小内容:
- 相关顶层目录和模块;
- 每个相关模块的一句话职责;
- 主要入口;
- 关键调用链或流程;
- 作为证据使用的公开契约和测试位置。
`ARCHITECTURE.md` 的最小内容:
- 观察到的层级或模块边界;
- 观察到的依赖方向;
- 主要控制或数据流程;
- 重要状态或数据的归属;
- 存在时的外部系统和运行边界。
所需文档存在后,把控制权交回依赖技能。生成文档始终只是观察到的上下文,直到用户明确将 `authority_status` 改为 `confirmed`。
### 仓库上下文验证
只有另一项技能因刚完成的前置任务,或仓库证据表明现有 `docs/REPO_MAP.md` 或 `docs/ARCHITECTURE.md` 对依赖任务可能过时时,才使用此模式。
1. 保留依赖技能的目标产物。
2. 阅读现有地图和 [仓库地图时效性检查清单](./references/staleness-checklist.md)。
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. 使用 [仓库地图时效性检查清单](./references/staleness-checklist.md) 判断地图是否可信,以及当前调用模式需要什么。
4. 使用 [代码放置分析准则](./references/placement-analysis.md) 作为质量标准而非固定模板,说明放置决定。除非任务跨越多个独立子系统或位置不确定性很高,否则保持简短。
5. 在已确定的职责边界内做最小可行修改。
6. 实施后使用 [仓库地图同步检查清单](./references/map-sync-checklist.md)。职责、文件、入口或流程改变时更新 `REPO_MAP.md`;层级、依赖或跨系统关系改变时也更新 `ARCHITECTURE.md`。
7. 报告职责、入口或关键流程是否改变,以及地图文档是否已同步。
## 工作原则
- 优先信任仓库证据,而非记忆中的或预期的架构。
- 先发现上下文,再问泛泛的位置问题。
- 只使用安全放置当前变更所需的最少地图细节。
- 明确的用户控制优先于自动路由判断。
- 区分职责边界和文件数量。
- 保持位置分析简洁,并聚焦实施。
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 |