Codespaces — 신념 맵 아키텍처 탐색은(는) 무엇을 하나요?
소스 파일을 읽기 전에 .belief_map.sexp을 질의하여 모듈, 경계, 의존성을 발견하십시오. 코드를 맹목적으로 읽지 말고 먼저 그래프를 질의하십시오.
스크립트
이 스킬은 Python 스크립트를 번들로 제공합니다. 스킬의 기본 디렉터리에서 실행하십시오:
scripts/belief_search.py— 신념 맵 그래프 질의scripts/build_belief_map.py— 소스에서 신념 맵 생성scripts/build_infra_topology.py— Kustomize, Helm, Terraform 토폴로지 사실 추출scripts/git_descendants.py— HEAD(또는 주어진 참조)로부터 내려오는 모든 커밋 찾기
프로젝트 로컬 복사본은 절대 사용하지 마십시오. 해당 복사본은 구식이거나 JSON을 출력할 수 있습니다.
전제 조건
신념 맵을 찾으십시오. 없으면 빌드하십시오:
ls .belief_map.sexp belief_map.sexp 2>/dev/null
# 빌드: pip3 install tree-sitter tree-sitter-typescript tree-sitter-python
python3 scripts/build_belief_map.py # 증분 ~5초
python3 scripts/build_belief_map.py --full # 전체 재빌드 ~30초
필수 워크플로: 코드보다 먼저 질의
중요한 코드 작업의 경우, rg, find, sed, cat, nl, 디렉터리 열기, 소스 파일 읽기 전에 신념 맵 질의를 실행하십시오. 이 스킬은 소스를 이미 확인한 후 확인용으로 사용될 때가 아니라 최초 범위 지정 단계로 사용될 때만 도움이 됩니다.
명확한 키워드가 있는 작업의 빠른 첫 패스:
python3 scripts/belief_search.py quick "키워드"
quick은 첫 번째 일치 모듈을 검색하고 즉시 analyze를 실행합니다. 경계 파일, 의존성, 역의존성, 계층, 위반을 한 번에 얻는 데 사용하십시오. quick이 잘못된 모듈을 반환하거나 일치 항목이 없는 경우 아래의 명시적 search -> analyze 흐름을 사용하십시오.
1단계 — 모듈 ID 찾기:
python3 scripts/belief_search.py search "키워드"
python3 scripts/belief_search.py entity 엔티티명
search 또는 entity를 사용하여 모듈 ID를 찾으십시오. 모듈 ID는 ps34와 같은 짧은 코드가 아닌 pki-service/src/modules/ca/ca.service와 같은 전체 상대 경로입니다. 신념 맵은 내부적으로 짧은 경로-맵 ID를 포함할 수 있지만 자동으로 해석됩니다. 항상 사람이 읽을 수 있는 경로와 유사한 문자열을 전달하십시오. 모듈 ID를 추측하거나 임의로 만들지 말고 항상 먼저 search로 확인하십시오.
2단계 — 모듈 분석 (즉시 수행, 선택 사항이 아님):
python3 scripts/belief_search.py analyze <모듈-id>
analyze는 기본 명령어입니다. 경계 파일, 의존성, 역의존성, 아키텍처 계층, 위반을 포함한 전체 컨텍스트를 반환합니다. 소스 코드를 읽기 전에 항상 실행하십시오.
3단계 — 분석 출력에 나열된 경계 파일만 읽으십시오.
4단계 — 전체 디렉터리를 읽지 마십시오. 경계에 2-3개의 관련 파일이 표시되면 해당 파일만 읽으십시오. 디렉터리의 다른 모든 것은 무시하십시오.
명령어 참조
| 명령어 | 목적 | 예시 |
|---|---|---|
search "<패턴>" | 그래프에서 정규식 grep (모듈 ID 찾기) | search "operative.*service" |
analyze <id> | 전체 모듈 분석 (기본 명령어) | analyze drive/modules/drive/drive_schema |
quick <키워드> | 검색 + 첫 번째 일치 항목 분석 (단축) | quick operatives |
boundary <id> | 변경을 위해 읽을 파일 | boundary operatives.service |
boundary <id> --files-only | 파일 경로만 (간결) | boundary operatives.service --files-only |
entity <이름> | 정의 + 참조 찾기 | entity DrivePath |
deps <id> [깊이] | 나가는 의존성 트리 | deps operatives.service 3 |
rdeps <id> [깊이] | 블래스트 래디어스 (이것에 의존하는 것) | rdeps drive_schema 2 |
flow <id> <함수명> | 호출/데이터 흐름 추적 | flow drive_api fetchFiles |
module <id> | 가장자리가 있는 단일 모듈 | module operatives.controller |
boundaries [id|all] | 아키텍처 위반 확인 | boundaries all |
invariants [id|all] | 명명 규칙 위반 확인 | invariants all |
layers | 계층별 모든 모듈 표시 | layers |
find_function <이름> | 함수/메서드 정의 찾기 | find_function createOrder |
find_type <이름> | 타입/클래스/인터페이스/열거형 정의 찾기 | find_type DriveDbCommitResponse |
find_callchain <src> <tgt> [깊이] | 함수 간 호출 경로 추적 | find_callchain createOrder processPayment |
find_callers <함수명> [깊이] | 이 함수를 호출하는 곳 | find_callers handleRequest 3 |
find_calls <함수명> [깊이] | 이 함수가 호출하는 것 | find_calls createOrder 2 |
grep_functions <패턴> | 소스에서 함수 본문 검색 | grep_functions "validate.*input" |
diff_functions [ref] | git diff에서 변경된 함수 | diff_functions HEAD~3 |
query '<sexp>' | 구성 가능한 Scheme 질의 | query '(count (boundary "X"))' |
repl | 대화형 Scheme REPL | repl |
빠른 참조: rg 질의
Python 스크립트를 호출하지 않고 빠르고 목표 지향적인 조회가 필요할 때 rg로 신념 맵을 직접 질의하십시오. 번들 빌더는 .belief_map.sexp를 작성합니다. 저장소가 여전히 레거시 belief_map.sexp를 사용하는 경우 아래 명령어에서 해당 파일 이름으로 대체하십시오:
# 모듈에 대한 모든 사실
rg 'drive/modules/drive_db/api ' .belief_map.sexp
# 모듈을 임포트하는 곳
rg 'imports .* drive/modules/commons/result' .belief_map.sexp
# 모듈이 임포트하는 것
rg 'imports drive/modules/drive_db/api' .belief_map.sexp
# 엔티티에 대한 모든 참조
rg 'DriveDbCommitResponse' .belief_map.sexp
# 저장소의 모든 클래스
rg '^\(cls drive/' .belief_map.sexp
# 데이터 흐름 가장자리
rg 'data-flow' .belief_map.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).
Scheme 질의 언어
복잡한 분석을 위한 질의를 구성하십시오. 전체 참조는 references/scheme-queries.md를 참조하십시오.
필수 사항:
(boundary "id") ; 대상 + 의존성 + 역의존성 (변경 경계)
(entity "Name") ; 엔티티를 정의하는 모듈
(deps "id" 깊이) ; 나가는 의존성
(rdeps "id" 깊이) ; 역의존성
(find-function "name") ; 일치하는 함수 정의가 있는 모듈
(find-type "name") ; 일치하는 타입 정의가 있는 모듈
(find-callers "fn" 깊이) ; 함수를 호출하는 모듈
(find-calls "fn" 깊이) ; 함수가 호출하는 모듈
(intersect A B) ; 집합 교집합
(filter SET "pattern") ; 정규식 필터
(files SET) ; 파일 경로로 해석
(count SET) ; 멤버 수
(violations) ; 경계 위반이 있는 모듈
(layer "id") ; 모듈의 아키텍처 계층
분석 계획 패턴
코드를 수정하기 전에 질의로부터 계획을 구성하십시오:
; 1. 범위
(boundary "operatives.service")
(count (boundary "operatives.service"))
; 2. 아키텍처 제약
(violations "operatives.service")
(layer "operatives.service")
; 3. 교차 언어 경계
(filter (refs-to "DrivePath") "app-service")
; 4. 실행 가능한 파일로 좁히기
(filter (boundary "operatives.service") "dto")
(intersect (deps "controller" 2) (deps "service" 2))
; 5. 변경 후: 확인
(violations "operatives.service")
트리거 예시
다음과 같은 경우 소스 코드를 읽기 전에 이 스킬을 사용하십시오:
- 서비스, API, 작업, 이벤트, UI 흐름 또는 실패 동작을 언급하는 근본 원인 조사
- 서비스 간 또는 모듈 간 질문 ("X가 Y를 어떻게 호출합니까?", "이것이 어디에 저장되어 있습니까?" 포함)
- 답변이 코드 동작에 의존하는 Redmine 명확화
- 아키텍처 리뷰, 영향 분석, 공개 계약 변경, 블래스트 래디어스 확인
- 의존성 방향이나 모듈 소유권이 중요할 때 중요하지 않은 스테이징된 변경 검토
커밋 전용 작업, git-로그 요약, 수동 데모/서버 실행, 순수 브라우저 테스트, 세션 로그 분석에는 강제하지 마십시오.
오류 복구
명령어가 (error no-match ...)를 반환하는 경우:
- 동일한 ID로 재시도하거나 다른 ID를 추측하지 마십시오
- 더 넓은 키워드로
search를 실행하여 올바른 모듈 ID를 찾으십시오 :suggestions필드가 있으면 사용하십시오. 유사한 모듈 ID를 나열합니다
# 잘못된 예: ID 추측
python3 scripts/belief_search.py analyze ps34 # 실패: ps34는 짧은 경로-맵 ID
python3 scripts/belief_search.py analyze ca.service # 실패: 불완전한 경로
# 올바른 예: 먼저 검색한 후 결과의 전체 경로 사용
python3 scripts/belief_search.py search "ca.*service"
# 출력: pki-service/src/modules/ca/ca.service
python3 scripts/belief_search.py analyze pki-service/src/modules/ca/ca.service
안티패턴
- 모듈 ID 추측하기. 모듈 ID는 전체 상대 경로입니다 (예:
pki-service/src/modules/ca/ca.service).ps34와 같은 짧은 코드는 내부 경로-맵 ID이므로 직접 사용하면 안 됩니다. 항상 먼저search하십시오. - 빌드만 하고 질의하지 않기. 신념 맵을 빌드하고
search,analyze,boundary를 전혀 실행하지 않으면 가치가 전혀 없습니다. - 소스 읽기 후 질의하기. 첫 번째 소스 코드 읽기는
analyze출력의boundary-file라인에서 나와야 합니다. .belief_map.sexp전체 파일 읽기.search,analyze, 또는rg를 사용하여 특정 사실을 질의하십시오.- 모듈 간 작업에 신념 맵 건너뛰기. 소스 파일을 읽기 전에 항상 그래프를 질의하여 경계를 이해하십시오.
- 디렉터리의 모든 파일 읽기. 경계에 2-3개의 파일이 표시되면 해당 파일만 읽으십시오.
- 프로젝트 로컬 스크립트 사용하기. 항상 이 스킬의 번들 스크립트를 사용하십시오. 프로젝트 복사본은 S-표현식 대신 JSON을 출력할 수 있습니다.
그래프 재빌드
python3 scripts/build_belief_map.py # 증분 (~5초)
python3 scripts/build_belief_map.py --full # 전체 재빌드 (~30초)
python3 scripts/build_belief_map.py ./drive # 단일 하위 저장소
python3 scripts/build_belief_map.py --lsp # LSP 호출 계층 포함 (~1-5분)
구조적 변경(파일 추가/제거, 임포트 변경, 클래스 추가) 후 재빌드하십시오.
인프라 토폴로지
Kustomize, Helm, Terraform 파일에서 서비스 토폴로지를 추출합니다. 이 스크립트는 PyYAML이 필요합니다 (pip3 install pyyaml).
python3 scripts/build_infra_topology.py # 모든 IaC 자동 감지
python3 scripts/build_infra_topology.py --kustomize . # kustomize만
python3 scripts/build_infra_topology.py --helm ./charts # helm 차트만
python3 scripts/build_infra_topology.py --terraform ./infra # terraform만
python3 scripts/build_infra_topology.py --append .belief_map.sexp # 그래프에 병합
infra-node, k8s-depends, k8s-service, helm-depends, tf-depends, infra-maps 가장자리를 내보냅니다. 다음과 같이 질의하십시오:
rg 'infra-node' .belief_map.sexp # 모든 서비스
rg 'k8s-depends' .belief_map.sexp # 서비스 의존성
rg 'infra-node.*:component database' .belief_map.sexp # 모든 데이터베이스
rg 'infra-maps.*app-service' .belief_map.sexp # 인프라 -> 소스 코드 매핑