github-search（GitHub 搜索）

GitHub Search

Overview

Before writing a single line of code, determine whether someone on the planet has already solved the same problem and published the result. The strongest engineering move is recognizing when the work has already been done.

Core principle: Search GitHub repositories, package registries, and open-source ecosystems for existing implementations before building anything new. Harvest the best patterns from multiple projects. Attribute what you borrow. Respect licenses.

No exceptions. No workarounds. No shortcuts.

The Prime Directive

NO BUILDING FROM SCRATCH WITHOUT SEARCHING GITHUB FIRST

If you have not queried public repositories for prior solutions, you are burning time on reinvention. Searched three different ways and found nothing applicable? Document what you searched and why nothing fit. Then build.

No excuses:

• Do not "just start coding and research later"
• Do not assume uniqueness because the problem feels novel
• Do not skip research for "straightforward" features (straightforward features have the densest prior art)
• Do not reject repositories because they are imperfect (extract what is valuable)
• "I know how to implement this" is not the same as "I should implement this from zero"

When to Use

Mandatory when:

• Initiating a new feature or project
• Building something that plausibly exists as open source
• Weighing competing implementation strategies
• Seeking architectural precedents from real-world systems
• Evaluating frameworks, libraries, or tooling choices

Particularly valuable when:

• The task involves ubiquitous patterns (auth, CRUD, file handling, search, payments)
• Building a game (every genre has extensive open-source coverage)
• Creating a utility that addresses a known problem space
• Implementing algorithms or specialized data structures
• Setting up infrastructure (CI/CD, deployment pipelines, monitoring)
• Designing APIs, schemas, or protocols with established conventions

The Entry Protocol

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"];
}

BEFORE building anything:

1. SEARCH -- Query GitHub, package registries, and the broader open-source ecosystem
2. EVALUATE -- Assess candidates for quality, relevance, and license compatibility
3. DECIDE -- Use as dependency, harvest patterns, study as reference, or build from scratch
4. DOCUMENT -- Record what you found and why you chose your path
5. ONLY THEN -- Begin building

Search Methodology

Where to Search

Cast a wide net across multiple channels before concluding nothing exists.

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

Effective Querying

Multi-query discipline -- Never settle for a single search.

Minimum threshold before declaring "nothing exists": 3 distinct query formulations across at least 2 search channels.

What to Search For

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"];
}

Evaluating Repositories

When assessing discovered repositories, apply these signals systematically.

Minimum viable candidate: Has tests, has a license, updated within the past year, README explains usage.

Quick Evaluation Checklist

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

Pattern Harvesting

When a repository is not directly consumable but contains valuable patterns, extract intelligently.

Phase 1: Identify Extractable Value

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)

Phase 2: Adapt to Your Context

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)

Phase 3: Attribute the Source

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

License Compatibility

Before using any code from a discovered repository, verify license compatibility.

When uncertain: MIT and Apache 2.0 are safe for virtually any project. GPL requires your project to also be GPL. No license means all rights reserved by the author -- do not use.

Multi-Source Harvesting

For complex features, the optimal approach often combines patterns from several repositories.

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.

Report to the user:

Present discoveries as labeled options with links. Mark the recommendation with a star.

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 exception: Reference and repository selection is ALWAYS interactive — even in YoloMode, present the options and let the user pick. These choices are too impactful to auto-select.

Cognitive Traps

Guardrails

Prohibited actions:

• Starting implementation without searching first (minimum 3 queries)
• Rejecting all search results without evaluation
• Copying code without verifying license compatibility
• Using a repository with no license (legal risk)
• Assuming your solution will surpass a battle-tested one
• Omitting attribution when harvesting patterns

Required actions:

• Search with at least 3 different query formulations
• Evaluate candidates against the assessment criteria
• Verify license compatibility before using any code
• Document what you found and your rationale
• Harvest patterns even from repositories you do not use directly
• Report findings to the user with links, popularity metrics, and what you are extracting

Quick Reference

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

Integration

Invoked during:

• godmode:intent-discovery -- Search during "Explore project context" and research phases
• godmode:reference-engine -- Routed here for external code and library research
• godmode:task-planning -- Reference repositories in plan tasks
• godmode:system-design -- Discover reference architectures on public repositories

Complementary skills:

• godmode:codebase-research -- For searching WITHIN the current codebase for internal patterns, conventions, and existing implementations to match
• godmode:specification-first -- Feeds search findings into formal specifications
• godmode:ux-patterns -- Repositories for code patterns; UX system for design patterns
• godmode:design-integration -- Find design system repos for bootstrapping
• godmode:project-bootstrap -- Locate starter templates and boilerplate projects