project-references

---

项目参考

此技能会在 ~/projects/referenzen/ 下维护你自己的 GitHub 仓库本地镜像，让你无需猜测或盲目阅读所有仓库，就能查找约定和实现模式。

对参考项目的所有操作均为只读。只有 git clone 和 git pull 会写入该目录，不会进行其他修改。

---

说明

步骤 1：检查相关仓库是否已克隆

ls ~/projects/referenzen/

如果缺少所需仓库，先运行 scripts/clone-or-update.sh owner/repo 克隆它。

步骤 2：询问用户哪个参考项目最相关

不要盲目扫描所有仓库——这会占用上下文。询问：“你的哪个同类项目使用了这种模式？”或列出可用仓库，让用户选择。

步骤 3：有针对性地搜索——先找文件，再用 grep

使用 find 按名称定位文件，然后用 cat 或 grep 只读取相关部分。搜索命令和模式请参阅 references/search-patterns.md。

步骤 4：采用模式时注明来源

在应用模式前，始终说明该模式来自哪个项目和文件路径：

采用的模式来自 your-service → helm-charts/Chart.yaml 第 4 行

步骤 5：仅在明确要求时同步

只有当用户说“全部同步”或“更新所有参考”时才运行 scripts/sync-all.sh。对于单个仓库，优先使用 scripts/clone-or-update.sh。

---

示例

示例 1：查找 Helm chart 约定

用户说：“这个项目的 Helm chart 应该如何组织？”

操作：

1. 运行 ls ~/projects/referenzen/ 查看可用仓库
2. 询问：“应该参考哪个同类项目？”——用户回答 your-service
3. 运行 find ~/projects/referenzen/your-service -name "Chart.yaml" 定位文件
4. 阅读文件，记录其结构（apiVersion、依赖项、版本模式）
5. 采用相同结构；注明来源：“采用自 your-service/helm-charts/Chart.yaml”

结果：Helm chart 的结构与同类项目一致，并注明了可追溯的来源。

示例 2：检出新的参考仓库

用户说：“克隆我的 other-service 项目作为参考。”

操作：

1. 运行 bash scripts/clone-or-update.sh owner/other-service
2. 实时输出进度，让用户看到 CLONE/PULL/SKIP 状态
3. 运行 ls ~/projects/referenzen/other-service/ 并确认

结果：仓库已在本地可用于查找模式；未进行任何修改。

示例 3：查找配置模式

用户说：“如何像其他项目那样配置数据库连接池？”

操作：

1. 运行 ls ~/projects/referenzen/，选择相关的同类项目
2. 运行 grep -rn "database.pool" ~/projects/referenzen/your-service/src/main/resources/
3. 阅读相关配置部分
4. 注明来源：“模式来自 your-service/src/main/resources/application.yaml 第 42 行”

结果：使用经过验证的同类项目中的准确配置，而不是凭空猜测。

示例 4：概览 GitHub Actions 触发器

用户说：“我的项目会在什么时候运行 GitHub Actions——推送、PR 还是定时任务？”

操作：

1. 运行 bash scripts/list-workflow-triggers.sh（添加 --glob 可缩小到某个流水线，添加 --root 可指定其他检出目录）
2. 展示排序后的概览（星期/时间，提供易读格式和原始 cron），以及仅由事件触发的工作流
3. 指向生成的报告 target/workflow-triggers.md

结果：汇总所有参考仓库中按时间排序的触发器概览，并生成 Markdown 报告，无需逐个打开工作流文件。

---

仓库来源

支持两种来源——若存在手动列表，则优先使用：

1. 手动列表（~/claude-shared/projekte.txt）：每行填写一个 GitHub 仓库 URL 或 owner/name 标识；忽略空行和 # 注释。
2. 自动发现：当文件不存在或用户明确要求完整同步时，使用 gh repo list --limit 200 --json nameWithOwner。

---

脚本

‌scripts/ 中提供了两个现成脚本——请使用它们，而不要编写内联 Bash。两者都支持通过环境变量覆盖 REFERENZEN_DIR（默认值： ~/projects/referenzen）。

scripts/clone-or-update.sh <owner/repo>

克隆单个仓库；如果仓库已在本地存在，则执行拉取。存在本地更改时会拒绝拉取（退出代码为 2）——绝不会暂存或重置更改。

bash scripts/clone-or-update.sh owner/your-repo

退出代码：0 = 成功，2 = 已跳过（存在本地更改），3 = 克隆/拉取失败。

scripts/sync-all.sh [--list <file>] [--limit <n>]

遍历所有仓库，并对每个仓库调用克隆或更新逻辑。优先使用 ~/claude-shared/projekte.txt 作为来源；如果该文件不存在，则回退到 gh repo list。最后会打印一行摘要。

# Sync everything (auto-detect source)
bash scripts/sync-all.sh

# Use a specific list file
bash scripts/sync-all.sh --list ~/claude-shared/projekte.txt

# Limit gh repo list to 50 repos
bash scripts/sync-all.sh --limit 50

不要盲目运行 sync-all——仅在用户明确说“同步全部”或“更新所有参考项目”时使用。对于单个仓库，请优先使用 clone-or-update.sh。

scripts/list-workflow-triggers.sh [--root <dir>] [--glob <pattern>] [--out <file>] [--no-report]

扫描每个仓库检出目录中的 .github/workflows/*.yml 和 *.yaml，提取 on: 块中的触发器（push、pull_request、schedule、 workflow_dispatch、release 等）以及任何 cron: 表达式，打印概览并写入 Markdown 报告。计划工作流会按星期/时间排序，并在原始 cron 表达式旁显示易读的运行时间（例如 Monday 02:05）；没有计划时间的工作流则单独列在仅包含事件的部分中。只读，不访问网络。

• --root <dir> — 包含仓库检出目录的目录。默认值： $REFERENZEN_DIR 或 ~/projects/referenzen。
• --glob <pattern> — 可选的文件名筛选条件，例如 maven-build.yml。 默认值：所有工作流。
• --out <file> — Markdown 报告路径。默认值：target/workflow-triggers.md （相对于当前项目目录；若目录不存在则会创建）。
• --no-report — 仅打印到标准输出，不生成报告文件。

# Overview + report for all reference repos
bash scripts/list-workflow-triggers.sh

# Only maven-build.yml, custom report location
bash scripts/list-workflow-triggers.sh --glob 'maven-build.yml' --out target/maven-triggers.md

# A different checkout root (e.g. Windows mount)
bash scripts/list-workflow-triggers.sh --root /mnt/c/Development/projects/all-git-repos

---

工作流

1. 检出或更新仓库

运行适当的脚本并实时输出内容，让用户看到每个 CLONE / PULL / SKIP 操作的执行过程。

2. 在参考项目中搜索

根据用户的实际需求限定搜索范围。优先进行针对性查找，而不是大范围递归 grep。现成的搜索命令和引用模式，请参阅 references/search-patterns.md。

3. 发现可用的参考项目

ls ~/projects/referenzen/

如果 ~/claude-shared/projekte.txt 存在，请同时展示其内容，以说明哪些仓库已纳入跟踪，哪些仓库已在本地存在。

4. GitHub Actions 触发器概览

运行 scripts/list-workflow-triggers.sh，获取各仓库中所有工作流的 on: 触发器和 cron: 条目的概览。该脚本还会将报告写入 target/workflow-triggers.md。使用 --glob 可筛选单个流水线（例如 maven-build.yml），使用 --root 可指定其他检出目录。

---

何时主动建议使用此技能

在以下情况下，建议查阅参考项目：

• 用户询问某项内容的结构方式，而答案可能因项目惯例而异（Helm chart 布局、Flyway 迁移命名、Dockerfile 模式、Maven 插件顺序等）。
• 存在多个合理方案，且与同类项目保持一致很重要。
• 用户说“像其他项目一样”或“和之前一样”，但没有说明具体是哪个项目。

请询问用户最相关的参考项目，而不要扫描所有项目——扫描会占用大量上下文。

---

安全规则

• 绝不要编辑、暂存、提交或删除 ~/projects/referenzen/ 中的文件。
• 如果由于本地更改导致 git pull 失败，请清楚说明冲突并停止——不要暂存、重置或强制执行。
• 不要在回复中暴露包含机密的仓库内容（.env、凭据文件）——只读取并引用目录结构。