github-search

GitHub 搜索

概述

在编写哪怕一行代码之前，先确认世界上是否已经有人解决了同样的问题并发布了成果。最出色的工程决策，就是意识到这项工作早已有人完成。

核心原则： 在构建任何新东西之前，先在 GitHub 仓库、软件包注册表和开源生态中搜索现有实现。从多个项目中汲取最佳实践。注明借鉴之处。遵守许可证。

没有例外。没有变通办法。没有捷径。

首要指令

NO BUILDING FROM SCRATCH WITHOUT SEARCHING GITHUB FIRST

如果你没有查询公共代码仓库，寻找已有解决方案，那就是在浪费时间重复造轮子。用三种不同方式搜索，仍然找不到适用方案？记录你搜索了什么，以及为什么没有合适的方案。然后再开始构建。

不许找借口：

• 不要“先开始写代码，以后再调研”
• 不要因为问题感觉新颖，就认定它独一无二
• 不要因为功能“很简单”就跳过调研（简单功能往往已有最丰富的先例）
• 不要因为仓库不完美就否定它（提取有价值的部分）
• “我知道如何实现”不等于“我应该从零开始实现”

适用场景

必须执行：

• 开始开发新功能或新项目
• 构建可能已有开源实现的内容
• 权衡不同的实现策略
• 寻找真实系统中的架构先例
• 评估框架、库或工具的选择

尤其有价值的场景：

• 任务涉及常见模式（身份验证、CRUD、文件处理、搜索、支付）
• 开发游戏（每种游戏类型都有大量开源资源）
• 创建用于解决已知问题的实用工具
• 实现算法或专用数据结构
• 搭建基础设施（CI/CD、部署流水线、监控）
• 设计已有成熟惯例的 API、架构或协议

入门流程

digraph github_search_gate {
    rankdir=TB;
    start [label="Task: Build something", shape=doublecircle];
    search [label="SEARCH\nGitHub, registries,\nopen-source ecosystems", shape=box];
    found [label="Relevant repos found?", shape=diamond];
    evaluate [label="EVALUATE\nStars, maintenance,\ncode quality, license, fit", shape=box];
    usable [label="Directly usable\nas a dependency?", shape=diamond];
    install [label="INSTALL\nAdd as dependency", shape=box style=filled fillcolor=lightgreen];
    harvestable [label="Harvestable\npatterns?", shape=diamond];
    harvest [label="HARVEST\nExtract patterns, adapt\nto your codebase", shape=box style=filled fillcolor=lightyellow];
    studyable [label="Useful as a\nlearning reference?", shape=diamond];
    study [label="STUDY\nAbsorb architecture,\nthen build your own", shape=box];
    build [label="BUILD FROM SCRATCH\nRecord: searched, nothing fit", shape=box];
    record [label="Document search queries\nand findings", shape=box];

    start -> search;
    search -> found;
    found -> evaluate [label="yes"];
    found -> record [label="no"];
    record -> build;
    evaluate -> usable;
    usable -> install [label="yes - strong fit"];
    usable -> harvestable [label="no - too heavy\nor wrong scope"];
    harvestable -> harvest [label="yes - valuable patterns"];
    harvestable -> studyable [label="no - different paradigm"];
    studyable -> study [label="yes - learn from it"];
    studyable -> build [label="no - genuinely nothing relevant"];
}

在开始构建任何东西之前：

1. 搜索——查询 GitHub、软件包注册表和更广泛的开源生态
2. 评估——考察候选项目的质量、相关性和许可证兼容性
3. 决策——将其用作依赖项、汲取实践经验、作为参考，或从头构建
4. 记录——记录发现的内容以及选择该方案的原因
5. 然后再——开始构建

搜索方法

搜索渠道

在断定不存在之前，先通过多个渠道广泛搜索。

1. GitHub Search: github.com/search (code, repositories, topics)
2. GitHub Topics: github.com/topics/{topic}
3. WebSearch: "github {what you need} {tech stack}"
4. Package registries: npmjs.com, pypi.org, crates.io, rubygems.org, pkg.go.dev
5. Curated lists: awesome-{topic} repositories on GitHub
6. Framework ecosystems: official plugin/extension directories

高效查询

多查询原则——绝不要只进行一次搜索。

查询方式	示例	可发现内容
字面名称	tetris javascript	与该概念完全匹配的结果
问题描述	real-time collaboration websocket	解决相同问题的方案
技术栈 + 模式	vue authentication oauth2	特定技术的实现
探索同义词	kanban board / task tracker / project manager	概念相同、术语不同的结果
精选集合	awesome-react / awesome-python	经社区筛选的列表

在宣称“不存在”之前的最低要求： 至少使用 2 个搜索渠道，采用 3 种不同的查询表述。

搜索内容

digraph search_scope {
    "What am I building?" [shape=diamond];
    "Complete application?" [shape=diamond];
    "Feature or module?" [shape=diamond];
    "Search for full repos" [shape=box];
    "Search for libraries + example repos" [shape=box];
    "Search for code snippets + patterns" [shape=box];

    "What am I building?" -> "Complete application?" [label="assess"];
    "Complete application?" -> "Search for full repos" [label="yes"];
    "Complete application?" -> "Feature or module?" [label="no"];
    "Feature or module?" -> "Search for libraries + example repos" [label="yes"];
    "Feature or module?" -> "Search for code snippets + patterns" [label="no"];
}

评估仓库

评估发现的仓库时，请系统地应用以下信号。

信号	正面指标	负面指标
受欢迎程度	100+ 星（经社区验证）	0-5 星（未经验证）
维护情况	6 个月内有提交记录	停滞 2 年以上
社区健康度	讨论活跃、PR 已合并	数百个过时问题，维护者没有回应
许可证	MIT、Apache 2.0、BSD	GPL（如果你需要宽松许可）、完全没有许可证
代码规范	有测试、类型、文档，结构清晰	没有测试、没有类型、代码杂乱
依赖规模	依赖精简且广为人知	50+ 个传递依赖、冷门包
文档	清晰的设置说明、使用示例	README 为空或过时
相关性	满足你 70%+ 的需求	仅有间接关联

**最低可用候选项：**有测试、有许可证、过去一年内更新过，且 README 说明了用法。

快速评估清单

For each candidate repository:

1. STARS & FORKS: Gauge community trust (100+ stars is a reasonable floor)
2. LAST COMMIT: Anything older than 18 months is a maintenance risk
3. OPEN ISSUES: High count with no maintainer replies signals abandonment
4. LICENSE FILE: No license means you cannot legally use it
5. TEST DIRECTORY: No tests means no confidence in correctness
6. README QUALITY: Poor docs usually correlate with poor internal structure
7. DEPENDENCIES: Check for bloated or unmaintained transitive deps
8. RELEASE CADENCE: Regular releases indicate ongoing investment

模式提取

如果某个仓库无法直接使用，但包含有价值的模式，请有选择地提取。

阶段 1：找出可提取的价值

FROM the repository, extract:
- Architectural patterns (how they organized the project)
- Algorithm implementations (how they solved the hard parts)
- Data models (how they structured domain entities)
- Interface designs (how they shaped the public API)
- Error handling approaches (how they manage edge cases)
- Test strategies (how they verify similar functionality)

阶段 2：适配你的上下文

DO NOT copy-paste entire files.
DO extract the pattern and rewrite for your:
- Technology stack
- Naming conventions
- Design system (for UI code)
- Architectural layering
- Internal codebase conventions (use godmode:codebase-research to find them)

阶段 3：注明来源

In your codebase or documentation, note:
"Approach inspired by github.com/author/repo - [what was adapted]"

许可证兼容性

使用发现的仓库中的任何代码前，请先确认许可证兼容性。

你的项目许可证	兼容的源许可证
MIT	MIT、BSD、Apache 2.0、ISC、Unlicense
Apache 2.0	MIT、BSD、Apache 2.0、ISC、Unlicense
GPL	任意（GPL 对引入的代码没有限制）
专有	MIT、BSD、Apache 2.0、ISC、Unlicense
任意	绝不可使用：未声明许可证、AGPL（除非你完全遵守其要求）

**不确定时：**MIT 和 Apache 2.0 几乎适用于任何项目。GPL 要求你的项目也使用 GPL。没有许可证意味着作者保留所有权利——请勿使用。

多来源提取

对于复杂功能，最佳做法通常是结合多个仓库中的模式。

Example: Building a real-time collaborative editor

Repo 1 (github.com/x/rich-editor): Polished prosemirror integration
  -> Harvest: Editor initialization pattern, schema definition approach

Repo 2 (github.com/y/crdt-sync): Clean CRDT implementation for text
  -> Harvest: Conflict resolution algorithm, operation transformation logic

Repo 3 (github.com/z/ws-rooms): WebSocket room management
  -> Harvest: Connection lifecycle, reconnection strategy, presence tracking

Result: Your implementation synthesizes the strongest elements from 3 repos,
each designed by specialists in their domain.

向用户汇报：

将发现整理为带标签且附有链接的选项。用星号标记推荐选项。

I found [N] relevant repositories. Here are the top candidates:

**A)** [repo-name] — [stars] stars, [license]
   Link: [GitHub URL]
   Extractable: [specific patterns/code worth harvesting]
   Fit: [what percentage of your need it covers]

**B)** [repo-name] — [stars] stars, [license]
   Link: [GitHub URL]
   Extractable: [specific patterns/code worth harvesting]
   Fit: [what percentage of your need it covers]

**C)** [repo-name] — [stars] stars, [license]
   Link: [GitHub URL]
   Extractable: [specific patterns/code worth harvesting]
   Fit: [what percentage of your need it covers]

**D) Multi-source harvest** — Best patterns from all three ⭐ Recommended
   From A: [what to extract]
   From B: [what to extract]
   From C: [what to extract]
   Build from scratch: [what is unique to this project]
   Why: Combines battle-tested patterns from [N] production systems

Check out the repos and pick A, B, C, or D.

**YoloMode 例外：**参考资料和仓库的选择始终需要交互——即使在 YoloMode 中，也要展示选项并让用户选择。这些选择影响重大，不能自动决定。

认知陷阱

自我开脱	事实
“我自己构建比研究别人的代码更快。”	你还得无限期维护它。经过实战检验的代码缺陷更少。
“没有适用于我这个确切场景的东西。”	你试过 3+ 种查询变体了吗？部分匹配也很有价值。
“开源代码的质量不可靠。”	拥有 1k+ 星且带测试套件的仓库，质量往往胜过你在时间压力下写出的代码。
“直接开始写更快。”	你会花数小时解决别人已经解决过的问题。
“我想避免外部依赖。”	可以提取模式而不添加依赖。这些知识是免费的。
“许可证太复杂了。”	MIT/Apache/BSD 意味着可以免费使用。花两秒检查一下，就能避免重复造轮子。
“只有 100 行，不值得研究。”	别人写的这 100 行涵盖了边缘情况，胜过你写的、没有这些覆盖的 100 行。
“遇到困难时我再研究。”	先研究。遇到困难意味着你已经浪费了时间。

防护措施

禁止的操作：

• 未先进行搜索就开始实现（至少进行 3 次查询）
• 未评估就拒绝所有搜索结果
• 未验证许可证兼容性就复制代码
• 使用没有许可证的仓库（存在法律风险）
• 假设你的解决方案会胜过经过实战检验的方案
• 借鉴模式时不注明出处

必需的操作：

• 使用至少 3 种不同的查询表述进行搜索
• 根据评估标准评估候选项
• 使用任何代码前验证许可证兼容性
• 记录发现和理由
• 即使不直接使用，也要借鉴仓库中的模式
• 向用户报告发现，包括链接、受欢迎程度指标以及你提取的内容

快速参考

SEARCH -> EVALUATE -> DECIDE -> DOCUMENT -> BUILD

Search: 3+ queries across GitHub, registries, and curated lists
Evaluate: Stars, activity, tests, license, relevance
Decide: Use as dependency | Harvest patterns | Study as reference | Build from scratch
Document: What you searched, what you found, why you chose your path
Build: With patterns from research, not from assumptions

集成

调用时机：

• godmode:intent-discovery —— 在“探索项目背景”和研究阶段进行搜索
• godmode:reference-engine —— 路由至此，以研究外部代码和库
• godmode:task-planning —— 在计划任务中引用仓库
• godmode:system-design —— 在公开仓库中寻找参考架构

互补技能：

• godmode:codebase-research —— 在当前代码库中搜索内部模式、惯例和现有实现，以便遵循
• godmode:specification-first —— 将搜索发现纳入正式规范
• godmode:ux-patterns —— 用仓库寻找代码模式；用 UX 系统寻找设计模式
• godmode:design-integration —— 查找设计系统仓库以便快速搭建
• godmode:project-bootstrap —— 查找入门模板和样板项目