Community코딩 & 개발github.com

wingbox

대규모 저장소와 모놀리식 저장소를 위한 코드 그래프입니다. grep이나 파일을 읽기 전에, 변경 사항이 무엇을 망가뜨릴지(블래스트 반경, 영향 분석), 누가 파일, 함수, 타입 또는 패키지를 사용하는지, 기능이 어디에 구현되어 있는지, 어떤 파일을 먼저 읽어야 하는지, 또는 모듈과 패키지가 어떻게 서로 의존하는지 알고 싶을 때; 리팩터링, 패키지 간 변경 또는 중요하지 않은 편집 전에; 그리고 익숙하지 않은 코드베이스를 탐색할 때 사용하세요. Python, TypeScript, TSX, Rust, C#, Java, Go, Ruby, Ruby on Rails, PHP, Laravel, Blade, Livewire, Eloquent, Dart 및 Flutter에 대해 아키텍처 인식 코드 검색, 의존성 그래프, 호출 흐름, 모듈 경계 및 아키텍처 위반을 구축하고 쿼리합니다.

wingbox란 무엇인가요?

wingbox는 대규모 저장소와 모놀리식 저장소를 위해 설계된 코드 그래프 아키텍처 발견 도구입니다. 소스 파일을 읽기 전에 `.wingbox/index.sexp`에 있는 코드 그래프를 쿼리하여 모듈, 모듈 경계 및 의존성을 발견할 수 있습니다. 주요 사용 사례는 변경 영향 분석(블래스트 반경), 파일/함수/타입/패키지 사용자 식별, 리팩터링 전 의존성 이해, 그리고 익숙하지 않은 코드베이스 탐색입니다. Python, TypeScript, Rust, C#, Java, Go, Ruby, PHP, Dart 및 Flutter 등 다양한 언어를 지원하며, CLI 명령어나 `/wingbox`(또는 `$wingbox`)를 통해 Codex, Claude Code, Cursor 및 기타 AI 어시스턴트와 통합됩니다. 사용자는 `wingbox build`로 그래프를 구축하고, `search`, `analyze`, `impact`, `usages`, `boundary` 등의 명령어로 그래프를 쿼리합니다. 이 도구는 코드를 읽기 전에 항상 그래프를 먼저 쿼리하여 파일을 무분별하게 읽는 것을 방지하고, S-표현식 출력을 통해 AI 에이전트와 시스템 간의 구조화된 데이터 교환을 지원합니다.

지원 대상✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/aileron-tech/wingbox/tree/HEAD

Installed? Explore more 코딩 & 개발 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

Wingbox -- 코드 그래프 아키텍처 발견

소스 파일을 읽기 전에 .wingbox/index.sexp을 쿼리하여 모듈, 경계 및 의존성을 발견하십시오. 코드를 무분별하게 읽지 말고 그래프를 먼저 쿼리하십시오.

/wingbox

사용자가 /wingbox(Codex에서는 $wingbox)를 입력하면, 다른 모든 작업보다 먼저 다음을 수행하십시오:

  • /wingbox 인수 없음: 그래프(.wingbox/index.sexp 파일을 프로젝트 루트에서 찾습니다; 모든 wingbox 명령은 하위 폴더에서도 찾습니다)를 찾습니다. 그래프가 없거나 오래된 경우 wingbox build .로 빌드합니다. 그래프는 프로젝트 파일이 그래프 파일보다 나중에 수정된 경우 오래된 것입니다. 다음 명령으로 확인할 수 있습니다:

    G=.wingbox/index.sexp
    [ ! -f "$G" ] || find . -type f -newer "$G" -not -path './.git/*' \
      -not -path './.wingbox/*' -not -path '*/node_modules/*' -print -quit
    

    재빌드는 내용이 변경된 파일만 다시 구문 분석합니다. 그런 다음 .wingbox/REPORT.md를 읽고 사용자에게 "주요 발견 사항", 가장 많이 의존하는 모듈 및 읽기를 시작할 위치를 알려주고, 지도가 .wingbox/map.html에 있다고 말하십시오(wingbox open은 브라우저에서 오프라인으로 보여줍니다).

  • /wingbox <file>: wingbox impact <file> 2를 실행하고 파일에 의존하는 항목과 먼저 읽어야 할 파일을 요약합니다.

  • /wingbox <command> ...: wingbox <command> ...을 실행합니다(예: /wingbox quick "file upload", /wingbox analyze src/billing/invoice).

명령 실행

wingbox 명령이 설치된 경우(command -v wingbox), 아래의 모든 쿼리에 대해 wingbox <command> ...을 실행하고 wingbox build PATH로 빌드합니다. 이 명령들은 스크립트와 동일한 인수를 받습니다. wingbox install에 의해 설치된 스킬은 scripts/ 폴더가 없으며 항상 명령을 사용합니다.

명령목적
`wingbox install [--global--project] [--assistant NAME ...] [--dry-run]`
`wingbox uninstall [--global--project] [--assistant NAME ...]`
wingbox open [PATH]프로젝트의 .wingbox/map.html을 브라우저에서 엽니다(브라우저가 없으면 경로를 출력합니다)
wingbox update [--check] [--dry-run]pipx, uv 또는 pip로 업그레이드한 다음 설치된 스킬, 블록 및 훅을 새로 고칩니다. 이전 버전이 남긴 파일(.code_graph*, wingbox-out/)에 대해 경고합니다
wingbox hook pre-searchClaude Code PreToolUse 훅; stdin에서 훅 입력을 읽습니다. 읽기 전에 그래프를 새로 고칩니다
wingbox hook dirty편집 및 쓰기에 대한 Claude Code PostToolUse 훅: 변경된 파일을 표시하여 다음 사용 전에 그래프가 새로 고쳐지도록 합니다

이 각각은 사실을 텍스트로 출력합니다. --sexp를 추가하면 S-표현식으로 출력합니다.

스크립트

이 스킬에는 Python 스크립트가 번들로 제공됩니다. 스캔된 프로젝트가 항상 명시적이도록 실행하기 전에 스킬 및 대상 루트를 확인하십시오:

  • scripts/code_graph_search.py -- 코드 그래프 쿼리
  • scripts/build_code_graph.py -- 소스에서 코드 그래프 생성
  • scripts/build_infra_topology.py -- Kustomize, Helm 및 Terraform 토폴로지 사실 추출
  • scripts/git_descendants.py -- HEAD(또는 주어진 참조)에서 내려오는 모든 커밋 찾기

프로젝트 로컬 복사본의 이러한 스크립트는 절대 사용하지 마십시오. 오래되어 JSON 대신 sexp을 출력할 수 있습니다.

전제 조건

코드 그래프를 찾으십시오. 없으면 빌드하십시오:

ls .wingbox/index.sexp 2>/dev/null
SKILL_ROOT="$(pwd -P)"
TARGET_ROOT="$(cd /absolute/path/to/project && pwd -P)"
python3 "$SKILL_ROOT/scripts/build_code_graph.py" --root "$TARGET_ROOT"
python3 "$SKILL_ROOT/scripts/build_code_graph.py" --root "$TARGET_ROOT" --full

Python 인덱싱에는 외부 파서 종속성이 없습니다. 다른 감지된 언어의 경우, 첫 번째 빌드는 파서가 없거나 버전이 잘못된 경우 게시 전에 실패하고 다음과 같이 언어별 정확한 명령을 인쇄합니다:

python3 -m pip install -r "$SKILL_ROOT/requirements/typescript.txt"
python3 -m pip install -r "$SKILL_ROOT/requirements/csharp.txt"
python3 -m pip install -r "$SKILL_ROOT/requirements/ruby.txt"
python3 -m pip install -r "$SKILL_ROOT/requirements/php.txt"
python3 -m pip install -r "$SKILL_ROOT/requirements/dart.txt"

빌더가 지정한 요구 사항 파일만 설치한 다음 다시 실행하십시오. requirements.txt는 인프라 토폴로지 종속성을 위해 예약되어 있습니다.

필수 워크플로: 코드보다 먼저 쿼리

중요하지 않은 코드 작업의 경우, rg, find, sed, cat, nl, 디렉토리 열기 또는 소스 파일 읽기 전에 코드 그래프 쿼리를 실행하십시오. 이 스킬은 소스를 이미 검사한 후의 확인이 아니라 첫 번째 범위 지정 단계로 사용될 때만 도움이 됩니다.

작업에 명확한 키워드가 있을 때 빠른 첫 번째 패스:

python3 scripts/code_graph_search.py quick "keyword"

quick은 첫 번째 일치하는 모듈을 검색하고 즉시 analyze를 실행합니다. 이를 사용하여 경계 파일, 종속성, 역종속성, 계층 및 위반을 한 번에 가져오십시오. quick이 잘못된 모듈을 반환하거나 일치하는 항목이 없으면 아래의 명시적인 search -> analyze 흐름을 사용하십시오.

1단계 - 모듈 ID 찾기:

python3 scripts/code_graph_search.py search "keyword"
python3 scripts/code_graph_search.py entity EntityName

search 또는 entity를 사용하여 모듈 ID를 찾으십시오. 모듈 ID는 billing-service/src/modules/invoice/invoice.service와 같은 전체 상대 경로이지 bs34와 같은 짧은 코드가 아닙니다. 코드 그래프는 내부적으로 짧은 경로 맵 ID를 포함할 수 있지만 자동으로 확인됩니다. 항상 사람이 읽을 수 있는 경로와 유사한 문자열을 전달하십시오. 모듈 ID를 추측하거나 만들어내지 말고 항상 search로 먼저 확인하십시오.

2단계 - 모듈 분석(즉시 수행, 선택 사항이 아님):

python3 scripts/code_graph_search.py analyze <module-id>

analyze는 기본 명령입니다. 전체 컨텍스트인 경계 파일, 종속성, 역종속성, 아키텍처 계층 및 위반을 반환합니다. 소스를 읽기 전에 항상 실행하십시오.

3단계 - 분석 출력에 나열된 경계 파일만 읽으십시오.

4단계 - 전체 디렉토리를 읽지 마십시오. 경계에 2-3개의 관련 파일이 표시되면 해당 파일만 읽으십시오. 디렉토리의 다른 모든 것은 무시하십시오.

명령 참조

명령목적예시
search "<pattern>"그래프에서 안전한 리터럴/.* 검색search "operative.*service"
analyze <id> [--all]전체 모듈 분석(기본 명령); --all이 아니면 최대 200개의 종속 항목 이름 지정; 모듈과 관련된 (advice ...)로 끝남analyze drive/modules/drive/drive_schema
quick <keyword>첫 번째 일치 항목 검색 + 분석(바로 가기)quick operatives
boundary <id>변경을 위해 읽을 파일boundary operatives.service
boundary <id> --files-only파일 경로만(간결)boundary operatives.service --files-only
entity <Name> [--positions]정의 + 이를 사용하는 모듈 찾기; --positions: 줄과 열이 있는 모든 사용entity DrivePath --positions
usages <symbol> [--sexp] [--all]재내보내기 및 별칭을 통한 하나의 심볼(Name, <file>::Name, <file>::Class.method)의 모든 사용, 파일, line:col 및 종류(import, re-export, call, type, extends, reference; 수신자 유형이 보이지 않는 메서드 호출의 경우 unresolved-call)별; --all이 아니면 최대 200개; 여러 파일에 정의된 이름은 후보를 나열합니다usages src/billing/invoice.ts::Invoice
deps <id> [depth]나가는 의존성 트리deps operatives.service 3
rdeps <id> [depth]블래스트 반경(이것에 의존하는 사람)rdeps drive_schema 2
`impact <fileid> [depth] --sexp [--all]`하나의 파일의 블래스트 반경: 최단 깊이별 종속 항목 + 먼저 읽을 파일; --all이 아니면 최대 200개 나열, 개수는 항상 완전함; 파일과 관련된 조언으로 끝남
flow <id> <fn>호출/데이터 흐름 추적flow drive_api fetchFiles
module <id>가장자리가 있는 단일 모듈module operatives.controller
wingbox init [PATH] [--force] [--sexp] [--synonyms]저장소를 부분으로 분할하고 각각의 아키텍처 스타일을 판단(점수, 증거 및 소스 포함)하고 .wingbox/config.yaml에 씁니다(--force가 아니면 유지됨); --synonyms는 내장 워드 벡터를 통해 폴더 이름도 매핑합니다; 빈 폴더에서 --language L --style S --yes [--scaffold]는 새 프로젝트를 시작합니다(없으면 선택 사항을 인쇄하고 종료 코드 2로 종료)wingbox init --sexp
wingbox advice [--sexp] [--learned] / `wingbox advice acceptreject [--reason TEXT]`거부되거나 오래 무시된 권장 사항 없이 마지막 빌드의 권장 사항(이동, 위반 수정, 누락 폴더)을 엽니다; .wingbox/decisions.sexp에 결정을 기록합니다
wingbox align [PART] [--to STYLE] [--learn] [--sexp]각 부분과 스타일 간의 격차(배치된 파일, 준수된 규칙, 배치되지 않은 폴더, 위반된 규칙); --to는 다른 스타일에 대해; --learn은 학습된 폴더와 기준선을 작성하여 새로운 위반만 보고되도록 합니다wingbox align --sexp
wingbox place "<what>" [--part PART] [--sexp]부분 스타일의 배치 규칙에 따른 새 코드의 계층 및 폴더(:new는 폴더가 아직 존재하지 않는 경우) 및 가져올 수 있는 항목wingbox place "repository for invoices" --sexp
wingbox compare [--sexp]언어별 모놀리식 저장소의 부분: 스타일, 계층, 차이점(누락된 계층, 다른 계층을 의미하는 폴더 이름, 다수와 다른 스타일) 및 벗어난 부분에 대한 조언wingbox compare --sexp
wingbox learn --agent [PART] [--sexp] / wingbox learn --apply [FILE]/wingbox learn: wingbox learn --agent 실행, 이름이 지정된 파일 읽기, 형식에만 답변((layer <part> <folder> <layer> :because "..."), (unknown ...), 최대 하나의 (style ...)), 답변을 wingbox learn --apply로 파이프하고 결과 표시; 오류 시 이름이 지정된 줄을 수정하고 전체 답변을 다시 보냄; 코드가 폴더를 결정하지 못하면 채팅에서 사용자에게 물어보고 :because "operator: <their words>"로 답변; 절대 추측하지 마십시오. .wingbox/config.yaml을 변경하려면 상단의 지침을 따르십시오wingbox learn --agent
`boundaries [idall]`각 부분 스타일의 경계 규칙(또는 부분이 선언한 규칙)을 확인합니다. 각 줄은 :part, :style 및 :rule의 이름을 지정합니다. 타입 전용 가져오기 및 추측된 계층은 별도로 보고됩니다. 그런 다음 해당 계층이 허용하지 않을 수 있는 파일(capability-violation: 저장소 외부의 SQL, 인프라 외부의 아웃바운드 HTTP, 도메인의 프레임워크, :line 및 :evidence 포함) 및 스타일의 패턴 검사(pattern-violation). boundaries-ok은 모든 부분이 확인된 경우에만 해당됩니다. 선언된 규칙을 읽지 못했거나 결정된 스타일이 없는 부분은 boundaries-not-checked이며 boundaries-partial이 ok 대신 표시됩니다. 종료 상태: 2 확인되지 않음(선언된 규칙을 읽지 못함), 1 위반, 그 외 0 - 종료 2에서 통과를 보고하지 마십시오
`invariants [idall]`명명 규칙 위반 확인
layers부분, 스타일 및 각 계층을 설정한 규칙과 함께 계층별로 모든 모듈 표시layers
find_function <name>함수/메서드 정의 찾기find_function createOrder
find_type <name>타입/클래스/모듈/인터페이스/enum 정의 찾기find_type DriveDbCommitResponse
find_callchain <src> <tgt> [depth]함수 간 호출 경로 추적find_callchain createOrder processPayment
find_callers <fn> [depth]이 함수를 호출하는 사람find_callers handleRequest 3
find_calls <fn> [depth]이 함수가 호출하는 항목find_calls createOrder 2
grep_functions <pattern>소스에서 함수 본문 검색grep_functions "validate.*input"
diff_functions [ref]git diff에서 변경된 함수diff_functions HEAD~3
query '<sexp>'구성 가능한 Scheme 쿼리query '(count (boundary "X"))'
repl대화형 Scheme REPLrepl
wingbox mcp [--root DIR]이러한 명령을 stdio에서 MCP 서버의 도구로 실행(build, impact, usages, analyze, quick, boundary, deps, ...)하여 MCP 클라이언트용claude mcp add wingbox -- wingbox mcp

impact는 일반 파일 경로를 허용합니다. --sexp 없이 사람을 위해 읽을 수 있는 텍스트를 인쇄합니다. 에이전트는 --sexp를 전달하여 다른 모든 명령이 사용하는 형식인 간결한 S-표현식 형식으로 동일한 사실을 얻습니다.

빠른 참조: rg 쿼리

Python 스크립트를 호출하지 않고 빠르고 대상화된 조회가 필요한 경우 rg로 코드 그래프를 직접 쿼리하십시오. 빌더는 그래프를 .wingbox/index.sexp에 씁니다:

# 모듈에 대한 모든 사실
rg 'drive/modules/drive_db/api ' .wingbox/index.sexp

# 모듈을 가져오는 사람
rg 'imports .* drive/modules/commons/result' .wingbox/index.sexp

# 모듈이 가져오는 항목
rg 'imports drive/modules/drive_db/api' .wingbox/index.sexp

# 엔터티에 대한 모든 참조
rg 'DriveDbCommitResponse' .wingbox/index.sexp

# 저장소의 모든 클래스
rg '^\(cls drive/' .wingbox/index.sexp

# 데이터 흐름 가장자리
rg 'data-flow' .wingbox/index.sexp

# 구성 파일에서 읽은 이름으로 로드된 Python 모듈
rg 'registry-wires' .wingbox/index.sexp

이 한 줄짜리 명령은 빠른 확인에 유용합니다. 구조화된 출력 및 전체 분석을 위해서는 Python 스크립트 명령을 사용하십시오.

출력 표기법

모든 출력은 한 줄에 하나씩 S-표현식 사실입니다. 전체 형식은 references/sexp-notation.md를 참조하십시오.

주요 패턴:

(boundary <mod> :lang py :file <path> :purpose "<desc>")
(boundary-dep <mod> <dep> :lang ts :file <path> :relation imports)
(boundary-rdep <mod> <rdep> :lang tsx :file <path> :relation imports)
(boundary-summary <mod> :total 10 :deps 7 :rdeps 2)
(entity-def cls <mod> <Name> <line> :lang py :file <path>)
(violation <src> <tgt> :src-layer domain :tgt-layer api :via imports :lang ts "<reason>")
(result <module-or-path>)
(result-count 42)

:lang 값: py = Python (snake_case), ts = TypeScript (camelCase), tsx = TSX (PascalCase), rs = Rust, cs = C#, java = Java, go = Go, rb = Ruby, php = PHP, dart = Dart.

관련 스킬