Back to Details

project-references

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Project References

项目参考

This skill manages a local mirror of your own GitHub repositories under 
~/projects/referenzen/
and lets you look up conventions and implementation patterns without guessing or reading all repos blindly.
All operations are read-only on the reference projects themselves. Only 
git clone
and 
git pull
write into that directory — never edits.
此技能用于管理
~/projects/referenzen/
目录下自有GitHub仓库的本地镜像，让你无需猜测或盲目阅读所有仓库即可查找规范和实现模式。
所有针对参考项目的操作均为只读。只有
git clone
和
git pull
会向该目录写入内容——绝不允许编辑。

Instructions

操作步骤

Step 1: Check whether the relevant repo is already cloned

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

bash
ls ~/projects/referenzen/
If the needed repo is missing, run 
scripts/clone-or-update.sh owner/repo
to clone it first.
bash
ls ~/projects/referenzen/
如果所需仓库缺失，先运行
scripts/clone-or-update.sh owner/repo
进行克隆。

Step 2: Ask the user which reference project is most relevant

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

Do not scan all repos blindly — that fills context. Ask: "Which of your sibling projects uses this pattern?" or list the available repos and let the user pick.
不要盲目扫描所有仓库——这会占用上下文资源。可以问：“你的哪个兄弟项目使用了这种模式？”或者列出可用仓库让用户选择。

Step 3: Search targeted — file first, then grep

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

Use 
find
to locate a file by name, then 
cat
or 
grep
to read only the relevant section. For search commands and patterns, consult 
references/search-patterns.md
.
使用
find
按名称定位文件，然后用
cat
或
grep
仅读取相关部分。如需搜索命令和模式，请参考
references/search-patterns.md
。

Step 4: Cite the source when adopting a pattern

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

Always state which project and file path a pattern came from before applying it:
Pattern adopted from 
your-service
→ 
helm-charts/Chart.yaml
line 4
在应用模式之前，务必说明该模式来自哪个项目和文件路径：
模式源自
your-service
→ 
helm-charts/Chart.yaml
第4行

Step 5: Sync only when explicitly requested

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

Run 
scripts/sync-all.sh
only when the user says "sync all" or "update all references". For a single repo, prefer 
scripts/clone-or-update.sh
.
仅当用户说“同步所有”或“更新所有参考仓库”时，才运行
scripts/sync-all.sh
。对于单个仓库，优先使用
scripts/clone-or-update.sh
。

Examples

示例

Example 1: Looking up a Helm chart convention

示例1：查找Helm chart规范

User says: "How should I structure the Helm chart for this project?"
Actions:
  1. Run 
    ls ~/projects/referenzen/
    to see available repos
  2. Ask: "Which sibling project should I use as reference?" — user says 
    your-service
  3. Run 
    find ~/projects/referenzen/your-service -name "Chart.yaml"
    to locate it
  4. Read the file, note the structure (apiVersion, dependencies, version pattern)
  5. Apply the same structure; cite: "adopted from 
    your-service/helm-charts/Chart.yaml
    "
Result: Helm chart consistent with sibling projects, traceable source cited.
用户说：“我应该如何为这个项目构建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与兄弟项目保持一致，且来源可追溯。

Example 2: Checking out a new reference repo

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

User says: "Clone my other-service project as a reference"
Actions:
  1. Run 
    bash scripts/clone-or-update.sh owner/other-service
  2. Stream output so user sees CLONE/PULL/SKIP progress
  3. Confirm with 
    ls ~/projects/referenzen/other-service/
Result: Repo available locally for pattern lookups; no edits made.
用户说：“克隆我的other-service项目作为参考”
操作：
  1. 运行
    bash scripts/clone-or-update.sh owner/other-service
  2. 输出流信息，让用户看到CLONE/PULL/SKIP的进度
  3. 通过
    ls ~/projects/referenzen/other-service/
    确认结果
结果：仓库已在本地可用，可用于模式查找；未进行任何编辑。

Example 3: Finding a configuration pattern

示例3：查找配置模式

User says: "How do I configure the database pool like in the other projects?"
Actions:
  1. ls ~/projects/referenzen/
    — pick a relevant sibling project
  2. grep -rn "database.pool" ~/projects/referenzen/your-service/src/main/resources/
  3. Read the relevant config section
  4. Cite: "pattern from 
    your-service/src/main/resources/application.yaml
    line 42"
Result: Exact config from a proven sibling project, not guessed.
用户说：“我应该如何像其他项目那样配置数据库连接池？”
操作：
  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行”
结果：直接采用已验证的兄弟项目中的准确配置，而非猜测。

Repository source

仓库来源

Two sources are supported — prefer the manual list when it exists:
  1. Manual list (
    ~/claude-shared/projekte.txt
    ): one GitHub repo URL or 
    owner/name
    slug per line, blank lines and 
    #
    comments ignored.
  2. Automatic discovery: 
    gh repo list --limit 200 --json nameWithOwner
    when the file is absent or the user explicitly asks for a full sync.
支持两种来源——当手动列表存在时优先使用：
  1. 手动列表（
    ~/claude-shared/projekte.txt
    ）：每行一个GitHub仓库URL或
    owner/name
    格式的仓库标识，空行和
    #
    注释将被忽略。
  2. 自动发现：当文件不存在或用户明确要求完全同步时，使用
    gh repo list --limit 200 --json nameWithOwner
    。

Scripts

脚本

Two ready-made scripts live in 
scripts/
— use them instead of writing inline Bash. Both accept 
REFERENZEN_DIR
as an env override (default: 
~/projects/referenzen
).
scripts/
目录下有两个现成脚本——使用它们而非编写内嵌Bash命令。两者均接受
REFERENZEN_DIR
作为环境变量覆盖默认路径（默认：
~/projects/referenzen
）。

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

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

Clones a single repository or pulls if it already exists locally. Refuses to pull when local changes are present (exit code 2) — never stashes or resets.
bash
bash scripts/clone-or-update.sh owner/your-repo
Exit codes: 
0
= ok, 
2
= skipped (local changes), 
3
= clone/pull failed.
克隆单个仓库，若本地已存在则拉取更新。当本地存在更改时拒绝拉取（退出码2）——绝不进行暂存或重置操作。
bash
bash scripts/clone-or-update.sh owner/your-repo
退出码：
0
=成功，
2
=跳过（存在本地更改），
3
=克隆/拉取失败。

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

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

Iterates over all repositories and calls the clone-or-update logic for each. Prefers 
~/claude-shared/projekte.txt
as source; falls back to 
gh repo list
when the file is absent. Prints a summary line at the end.
bash
undefined
遍历所有仓库，并为每个仓库调用克隆或更新逻辑。优先使用
~/claude-shared/projekte.txt
作为来源；当文件不存在时回退到
gh repo list
。最后打印汇总信息。
bash
undefined

Sync everything (auto-detect source)

同步所有仓库（自动检测来源）

bash scripts/sync-all.sh
bash scripts/sync-all.sh

Use a specific list file

使用指定的列表文件

bash scripts/sync-all.sh --list ~/claude-shared/projekte.txt
bash scripts/sync-all.sh --list ~/claude-shared/projekte.txt

Limit gh repo list to 50 repos

将gh repo list限制为50个仓库

bash scripts/sync-all.sh --limit 50

**Do not** run sync-all blindly — use it only when the user explicitly says
"sync all" or "update all references". For a single repo prefer
`clone-or-update.sh`.

---
bash scripts/sync-all.sh --limit 50

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

---

Workflows

工作流程

1. Check out or update repositories

1. 检出或更新仓库

Run the appropriate script and stream output so the user sees every CLONE / PULL / SKIP action as it happens.
运行相应脚本并输出流信息，让用户实时看到每个CLONE/PULL/SKIP操作。

2. Search within reference projects

2. 在参考仓库中搜索

Scope the search to what the user actually needs. Prefer targeted lookups over broad recursive greps. For ready-made search commands and citing patterns, consult 
references/search-patterns.md
.
将搜索范围限定在用户实际需要的内容上。优先进行针对性查找，而非广泛的递归grep。如需现成的搜索命令和引用模式，请参考
references/search-patterns.md
。

3. Discover available reference projects

3. 发现可用的参考仓库

bash
ls ~/projects/referenzen/
If 
~/claude-shared/projekte.txt
exists, show its contents alongside to explain which repos are tracked vs. which are locally present.
bash
ls ~/projects/referenzen/
如果
~/claude-shared/projekte.txt
存在，同时显示其内容，以说明哪些仓库是被跟踪的，哪些是本地已存在的。

When to suggest this skill proactively

何时主动推荐此技能

Suggest looking up a reference project when:
  • The user asks how something is structured and the answer may vary by project convention (Helm chart layout, Flyway migration naming, Dockerfile patterns, Maven plugin ordering, etc.)
  • There is more than one reasonable approach and consistency with sibling projects matters
  • The user says "like the other projects" or "same as before" without specifying which project
Ask the user which reference project is most relevant rather than scanning all of them — scanning is expensive in context.
当出现以下情况时，建议查找参考项目：
  • 用户询问某项内容的结构，且答案可能因项目规范而异（如Helm chart布局、Flyway迁移命名、Dockerfile模式、Maven插件顺序等）
  • 存在多种合理实现方式，且与兄弟项目保持一致性至关重要
  • 用户说“像其他项目那样”或“和之前一样”但未指定具体项目
询问用户哪个参考项目最相关，而非扫描所有仓库——扫描会消耗大量上下文资源。

Safety rules

安全规则

  • Never edit, stage, commit, or delete files inside 
    ~/projects/referenzen/
    .
  • If 
    git pull
    would fail due to local changes, report the conflict clearly and stop — do not stash, reset, or force.
  • Do not expose repository contents that contain secrets (
    .env
    , credential files) in the response — read and cite structure only.
  • 绝不允许编辑、暂存、提交或删除
    ~/projects/referenzen/
    目录内的文件。
  • 如果因本地更改导致
    git pull
    失败，需清晰报告冲突并停止操作——不得进行暂存、重置或强制拉取。
  • 响应中不得暴露包含机密信息的仓库内容（如
    .env
    、凭证文件）——仅读取和引用结构。