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-search | Claude 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 <file | id> [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 accept | reject [--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 [id | all]` | 각 부분 스타일의 경계 규칙(또는 부분이 선언한 규칙)을 확인합니다. 각 줄은 :part, :style 및 :rule의 이름을 지정합니다. 타입 전용 가져오기 및 추측된 계층은 별도로 보고됩니다. 그런 다음 해당 계층이 허용하지 않을 수 있는 파일(capability-violation: 저장소 외부의 SQL, 인프라 외부의 아웃바운드 HTTP, 도메인의 프레임워크, :line 및 :evidence 포함) 및 스타일의 패턴 검사(pattern-violation). boundaries-ok은 모든 부분이 확인된 경우에만 해당됩니다. 선언된 규칙을 읽지 못했거나 결정된 스타일이 없는 부분은 boundaries-not-checked이며 boundaries-partial이 ok 대신 표시됩니다. 종료 상태: 2 확인되지 않음(선언된 규칙을 읽지 못함), 1 위반, 그 외 0 - 종료 2에서 통과를 보고하지 마십시오 |
| `invariants [id | all]` | 명명 규칙 위반 확인 |
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 REPL | repl |
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.