Insights
AI가 자동으로 큐레이션·번역·정리하는 기술 동향 피드입니다.
Clarity는 소스 코드 기반의 의존성 영향도 그래프를 구축하는 CLI 도구입니다. 이 도구는 파일, 모듈, 테스트 간의 연결 구조(결합도)를 시각화하여 보여줍니다. 개발자가 커밋 전 설계 변경이 어떤 영역에 영향을 미치는지 증거 기반으로 추론하고 리팩토링을 검증할 수 있게 돕습니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 GitHub Codex tools의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기Built with Clarity
License
Release
npm version
커밋하기 전에 코드 변경의 구조를 확인하세요.
Clarity는 소스 코드로부터 의존성 영향도 그래프(dependency impact graphs)를 구축합니다. 이 도구는 파일, 모듈, 테스트 및 문서화가 어떻게 연결되는지 보여줌으로써 개발자와 코딩 에이전트가 직관 대신 증거를 바탕으로 설계 변경에 대해 추론할 수 있게 합니다.
다음과 같은 경우에 Clarity를 사용하세요:
Clarity는 파일 단위로 작동합니다. 런타임 동작이나 전체 API 계약이 아닌 결합도(coupling shape)를 복구합니다.
npm으로 설치:
pm install -g @legacycodehq/clarity
또는 macOS/Linux에서 Homebrew로 설치:
brew install LegacyCodeHQ/tap/clarity
코딩하는 동안 라이브 그래프를 열어두세요:
clarity watch
커밋하지 않은 작업의 구조적 영향을 보여주세요:
clarity show
파일을 변경하기 전에 무엇이 의존하는지 확인하세요:
clarity show path/to/file.go --reach up
브랜치의 구조적 흔적(structural footprint)을 검토하세요:
clarity show -c main...HEAD
모든 그래프는 네 가지 질문에 답합니다.
| 질문 | 의미 | 예시 |
|---|---|---|
| 어떤 스냅샷인가요? (Which snapshot?) | 작업 트리(working tree), 커밋(commit) 또는 범위(range) | clarity show, -c HEAD, -c main...HEAD |
| ... |
이러한 특징 덕분에 Clarity는 빠른 로컬 확인과 반복 가능한 에이전트 워크플로우 모두에 유용합니다.
clarity show
커밋하지 않은 작업 주변의 의존성 그래프를 보여줍니다.
다음 사항을 확인하는 데 사용하세요:
clarity show -c HEAD
clarity show -c main...HEAD
커밋(commit) 및 범위 스냅샷(range snapshots)을 사용하여 사후에 구조적 영향을 검토할 수 있습니다. 이는 풀 리퀘스트(pull request), 회귀 테스트 기간(regression window), 릴리스 검토, 에이전트가 생성한 변경 사항 등에 유용합니다.
clarity show path/to/file.go --reach up
clarity show path/to/file.go --reach both --depth 2
파일을 변경하기 전에 업스트림 리치(upstream reach)를 사용하여 '누가 이것을 가져오는지?'에 대한 답을 얻으세요. 바운디드 리치(bounded reach)를 사용하여 영향 범위(blast radius)를 추정합니다.
clarity show src/auth
clarity show src/auth --reach both
clarity show --all --collapse
스코프 그래프(scoped graphs)를 사용하여 익숙하지 않은 코드를 탐색합니다. 파일 수준의 그래프가 너무 복잡할 때는 구성된 모듈을 축소(collapse)하세요.
clarity show --between ui/login.ts,server/session.go
두 파일을 연결하는 의존성 경로를 보여줍니다. 두 영역이 왜 결합(coupled)되어 있는지 설명해야 하거나, 어디서 의존성을 끊을지 결정해야 할 때 사용합니다.
clarity modules
clarity show --module auth --reach both
clarity show --all --collapse
모듈을 .clarity/modules.json에 선언하거나, 컨텍스트에서 모듈을 검사하거나, 아키텍처 수준 노드로 모듈을 축소할 수 있습니다.
clarity cycles src
clarity cycles src --explain
clarity cycles src --code-only
...
완전한 순환 의존성 구성 요소 목록을 나열하고, 대표적인 루프를 보여주며, 검증된 의존성 엣지 분리 세트(bounded components의 정확한 최소값 및 더 큰 구성요소에 대한 레이블이 지정된 휴리스틱)를 권장합니다. Explain 모드는 각 엣지 뒤에 있는 정확한 심볼과 소스 라인을 추가하며, code-only 모드는 마크다운 탐색 루프를 제외합니다. 시맨틱 필터는 그래프를 재구축하고 선택된 관계 유형에 대해 분리 세트를 다시 계산합니다. 실행 가능한 순환 분석을 참조하세요.
clarity watch
clarity watch src/auth --reach both
파일 변경에 따라 업데이트되는 로컬 라이브 그래프를 실행합니다. 리팩토링이나 대규모 에이전트 편집 시 구조적 피드백을 계속 확인할 수 있습니다.
clarity setup
코딩 에이전트가 일반적인 작업 루프의 일부로 Clarity를 사용할 수 있도록 저장소 지침을 추가합니다.
좋은 에이전트 패턴:
--reach up으로 종속성을 검사합니다.clarity show -f mermaid를 실행합니다.clarity show -u를 생성합니다.clarity show -f dot
clarity show -f mermaid
clarity show -u
기본값은 DOT입니다. Mermaid는 문서(docs), IDE, 에이전트 UI에서 잘 작동합니다. -u는 브라우저 친화적인 시각화 URL을 생성합니다.
Clarity는 다음 언어에 대한 의존성 추출을 지원합니다:
지원 품질은 언어별로 다릅니다. 현재 성숙도와 확장 목록을 보려면 다음을 실행하세요:
clarity languages
clarity cycles
clarity workspace
cycles는 완전한 순환 구성 요소(cyclic components), 소스 증거(source evidence), 그리고 검증된 사이클 파괴 권장 사항을 보고합니다. 실행 가능한 사이클 분석을 참조하세요.
workspace는 Go 모듈 및 Rust 크레이트 관계 그래프를 구축합니다.
이 기능 영역들은 유용하지만 여전히 실험적입니다. cycles의 경우, 안정화되기 전까지는 명령어 이름, 플래그, 관계 분류법(relationship taxonomy), Go 증거 유형, 사용자 출력 및 JSON 스키마가 호환성 공지 없이 변경될 수 있습니다.
Clarity는 테스트, 타입 검사(type checks), 린터(linters), 또는 코드 리뷰를 대체하는 것이 아닙니다.
다음 기능을 제공하지 않습니다:
이는 구조적 검증 도구입니다. 결합(coupling), 영향도(impact), 경계(boundaries), 사이클, 그리고 변경 형태를 보여줍니다.
본 프로젝트는 Apache License, Version 2.0에 따라 라이선스가 부여됩니다.
저작권 (c) 2026년~현재, Legacy Code Headquarters (OPC) Private Limited. 모든 권리 보유.