From e81217388ee278d6b45733b9e7b9619221196e07 Mon Sep 17 00:00:00 2001 From: vitya Date: Wed, 26 Aug 2026 08:41:38 +0300 Subject: [PATCH] =?UTF-8?q?feat(skill):=20code-search=20v0.1.0=20=E2=80=94?= =?UTF-8?q?=20rg-first=20code=20search=20(RED:=20grep=20-r=2015min+=20hang?= =?UTF-8?q?=20=E2=86=92=20GREEN:=20rg=200s;=20routing=20rg/git-grep/repo?= =?UTF-8?q?=5Fread/grep=5Faudit)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 1 + README.ru.md | 1 + dist/code-search.skill | Bin 0 -> 2919 bytes skills/code-search/SKILL.md | 98 ++++++++++++++++++++++++++++++++++++ 4 files changed, 100 insertions(+) create mode 100644 dist/code-search.skill create mode 100644 skills/code-search/SKILL.md diff --git a/README.md b/README.md index 2f2d68c..babd3e5 100644 --- a/README.md +++ b/README.md @@ -118,6 +118,7 @@ an explicit `adapted-from` marker in its frontmatter. | `loop-me` | `adapted-from: mattpocock/skills @ 84fdeffd` (MIT) — workflow-spec design gate | | `review-kit-pi-method` | `author: ours` — pi-native spawn for clean-context review subagents | | `command-index` | `author: ours` — just/Makefile command-index convention (standard targets, auto-doc; idea 3/18) | +| `code-search` | `author: ours` — rg-first code search (measured 15 min → 0s; routing: rg / git grep / interns repo_read / grep_audit) | | `code-review` | `adapted-from: mattpocock/skills @ 84fdeffd` (MIT) — two-axis + Fowler baseline; output: caveman-review format | | `writing-skills` | `adapted-from: obra/superpowers @ 6.2.0` (MIT) — TDD-for-skills core + ideya 8 self-skill-authoring | | `web-search` | `author: ours` — search_web tool (pi-extension) + policy: when to search, «без поиска» session-off | diff --git a/README.ru.md b/README.ru.md index 2c176bb..8b1ccdb 100644 --- a/README.ru.md +++ b/README.ru.md @@ -88,6 +88,7 @@ bash scripts/build.sh caveman # один | `loop-me` | `adapted-from: mattpocock/skills @ 84fdeffd` (MIT) — дизайн-гейт workflow-спец | | `review-kit-pi-method` | `author: ours` — pi-спавн чистых review-субагентов | | `command-index` | `author: ours` — конвенция just/Makefile command-index (стандартные таргеты, авто-док; идея 3/18) | +| `code-search` | `author: ours` — rg-first код-поиск (замер: 15 мин → 0 сек; роутинг: rg / git grep / interns repo_read / grep_audit) | | `code-review` | `adapted-from: mattpocock/skills @ 84fdeffd` (MIT) — двухосевость + Fowler-база; формат вывода: caveman-review | | `writing-skills` | `adapted-from: obra/superpowers @ 6.2.0` (MIT) — TDD-for-skills ядро + идея 8 self-skill-authoring | | остальные `skills/*` | `author: ours` | diff --git a/dist/code-search.skill b/dist/code-search.skill new file mode 100644 index 0000000000000000000000000000000000000000..d663c62ef965b91fab836ee29abc9e994fbb2cb2 GIT binary patch literal 2919 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 z002uC000yK00000000000000000000V{c?-EpugIa${&OQ%gxqOfGF?P)h{{00000 R0RRC2LI3~&4+{VQ005I*r~?21 literal 0 HcmV?d00001 diff --git a/skills/code-search/SKILL.md b/skills/code-search/SKILL.md new file mode 100644 index 0000000..08c8ef1 --- /dev/null +++ b/skills/code-search/SKILL.md @@ -0,0 +1,98 @@ +--- +name: code-search +author: ours +version: 0.1.0 +description: > + Use when searching code for strings, symbols, or usages — "find where X is + used", «найди, где используется», "grep for X", "where is X", "search the + repo for", any code search, or when deciding HOW to search a codebase. One + hard rule: in any tree that can contain node_modules/dist/build/.nuxt, + search with `rg` (gitignore-aware) — NEVER `grep -r` (`--include` filters + file names, not directory traversal; grep walks every node_modules entry: + measured 15+ min never-finishing vs rg 0s on the same tree). Routes: + string/symbol search → rg; tracked-files-only → git grep; whole-repo + comprehension ("what does module Y do") → interns repo_read (ask-mode); + N×M contains audits → interns grep_audit. Skip for web search + (web-search), vault search (coworker-search), already-fast tools. +--- + +# Code Search + +Search code with the fastest correct tool for the question class. The default +`grep -r` habit is the single biggest time sink in agent work on npm/JS +projects — the fix is a different binary, not more patience. + +## When to use + +- Any "where is X used / where does X appear / search the repo for X" request. +- Deciding HOW to search: rg vs git grep vs intern delegation. +- A search that "feels slow" — that is a wrong-tool signal, not a slow disk. + +## When NOT to use + +- Web search → `web-search` skill. +- Searching the .cowork vault / memory vault → `coworker-search`. +- A question ABOUT the code ("what does module Y do", "how does the build work") → `interns.repo_read` (delegation, ask-mode per `using-interns`). +- The right tool is already running and fast. + +## Core rule (one sentence) + +**In any tree that can contain `node_modules` / `dist` / `build` / `.nuxt` / `vendor`, search with `rg`, never `grep -r`.** + +Why — measured on `stostayer.new`, `packages/web` + `apps/web4`, 2026-08-26: + +| Fact | Value | +|---|---| +| Total files in the two dirs | 113,169 | +| Of which in `node_modules` + `.nuxt` + `build` | 109,248 (**96%**) | +| `grep -rn "3590" … --include=*.vue --include=*.js … -l` | **> 15 min, never finished** (RED run: fresh unprompted agent spawned 2× `/usr/bin/grep`, still running at 200s, killed) | +| `rg -l "3590" …` (same globs) | **0s**, 3 matches | +| `rg --no-ignore "3590" …` (forced full scan incl. node_modules) | 16s | + +Mechanics: `grep -r --include` filters which **file names** get read — it does +NOT stop **directory traversal**. grep stats/opens every directory entry +including node_modules (100k+ files) on every search. `rg` reads `.gitignore` +(+ `.ignore`, `.rgignore`) and skips ignored trees by default — zero flags +needed. It is already installed on this machine (ripgrep 15.x). + +## Routing table + +| Question class | Tool | Notes | +|---|---|---| +| Find string/symbol/usages in the working tree | `rg -n "pattern" ` | gitignore-aware out of the box. `-l` → filenames only. `-g '*.ext'` to filter. | +| Only tracked files (clean, deterministic) | `git grep -n "pattern"` | uses the git index; ignores untracked + ignored. Always present even on bare boxes. | +| "I really must scan generated/vendored too" | `rg --no-ignore` | 16s on the 113k-file tree — still ~50× faster than grep. Never `grep -r` even here. | +| Whole-repo comprehension ("what does module Y do", "where is X used across the architecture") | `interns.repo_read` | delegation — ask-mode, `using-interns` skill. Packs via repomix + cheap LLM. | +| N×M contains/not-contains audit (canonical strings across many files) | `interns.grep_audit` | deterministic, no LLM call. | + +## Common mistakes / rationalizations + +| Excuse | Reality | +|---|---| +| "grep works, just slow" | Wrong tool. rg is a drop-in replacement on the same globs: 15 min → 0s on the same tree. | +| "--include excludes node_modules" | **False.** `--include` filters file *names* that get read, not directories *walked*. grep still traverses all 100k+ node_modules entries. | +| "Windows/Defender is just slow" | The disk is not the problem — 96% of walked files are build artifacts. rg skips them via .gitignore before the filesystem ever opens them. | +| "I need to search EVERYTHING" | Use `rg --no-ignore` (16s), still not grep (15 min). Scope with `-g '!node_modules'` if noise is the issue. | +| "rg isn't installed here" | It is (ripgrep 15.2.0). On a bare box fall back to `git grep` — git is always present. | +| "It's a one-off, speed doesn't matter" | One-off searches happen 10+ times per session. Each 15-min grep burns an entire agent turn for nothing. | + +## Red flags (STOP) + +- A search command starting with `grep -r` in any JS/TS/node project — rewrite to `rg` before running. +- A grep that "hasn't returned" after 30s — it is walking node_modules; kill it, use rg. +- Search results containing `node_modules/` / `.nuxt/` / `dist/` paths — you scanned garbage; redo with rg (ignore-aware). +- Writing `--include` and believing directories are excluded. + +## Cross-agent applicability + +Tool-level rule, works in any agent that can run shell commands (pi, claude, +codex exec, hermes). `rg` or `git grep` are the always-available core; the +intern rows are optional delegation for a local `interns` MCP +(`using-interns` skill). The core rule stands alone without them. + +## Out of scope + +- Semantic code search / index servers (zoekt, sourcegraph, codesearch) — YAGNI; rg removes the pain without infrastructure. +- Searching non-code stores (vaults, wikis, the web). +- Teaching rg's full flag surface — `rg --help` / man. +- mappa internals: code search stays client-side (operator decision 2026-08-25 — "rg-мост по чек-аутам", outside mappa).