Onboard-CLI, 코드베이스 지도를 로컬에서 그리다
AI 코딩 도구의 병목은 코드 생성보다 코드베이스 이해와 경계 유지로 옮겨가고 있다. Onboard-CLI 같은 로컬 AST 지도는 에이전트가 변경 전에 지형을 읽게 만드는 인프라다.
AI 뉴스를 놓치지 마세요
매주 핵심 AI 소식을 이메일로 받아보세요.
코드 생성보다 먼저 필요한 것은 지도다
Onboard-CLI는 Go로 작성된 CLI와 React 기반 로컬 시각화 도구를 결합해 대형 코드베이스의 구조를 보여주는 프로젝트다. README는 이 도구가 Tree-sitter 기반 AST 파싱으로 Go, TypeScript, JavaScript, Python, Java를 분석하고, React Flow 캔버스에서 의존 경로와 토폴로지 지도를 보여준다고 설명한다. 또한 architecture.yml 규칙을 기준으로 금지된 import와 경계 위반을 탐지하는 drift 명령도 제공한다.
이런 도구가 HN에서 관심을 받는 이유는 분명하다. AI 코딩 도구가 코드를 빠르게 쓰게 만들수록, 팀은 "무엇을 바꿔도 되는가"를 더 자주 잃는다. LLM은 파일을 열고 수정할 수 있지만, 모듈 경계, 소유권, 암묵적 의존성, 오래된 예외 규칙을 항상 이해하지는 못한다. Onboard-CLI는 생성 모델 자체가 아니라 모델이 작업하기 전후에 봐야 할 구조 정보를 만든다.
Agenthub의 htmx와 AI 코딩의 거리감, OfficeCLI 문서 에이전트, Codex 추론 토큰 클러스터링과 같은 흐름에서 보면, Onboard-CLI는 "생성"보다 "이해와 검증" 쪽의 개발자 도구다.
기능보다 중요한 설계 방향
Onboard-CLI의 주요 명령은 init, map, routes, drift, impact, owners, export, pulse로 구성된다. map은 특정 타깃과 radius를 받아 로컬 시각화 서버를 띄우고, routes는 Express, Gin, FastAPI, Spring 같은 프레임워크의 REST 라우트를 실제 파일과 라인 위치에 매핑한다. drift는 architecture.yml 규칙을 기준으로 아키텍처 위반을 찾는다.
기술 스택도 현재 개발자 도구의 방향을 보여준다. CLI는 Go와 Cobra, Go Tree-sitter, YAML을 쓰고, UI는 React 19, Vite, @xyflow/react, Tailwind CSS, Framer Motion으로 구성됐다. 이는 터미널 명령과 풍부한 캔버스 UI를 함께 제공하는 방식이다. 단순 텍스트 출력만으로는 복잡한 코드베이스 구조를 팀이 공유하기 어렵기 때문이다.
| 영역 | Onboard-CLI 접근 | AI 코딩에서의 의미 | 주의점 |
|---|---|---|---|
| 코드 이해 | Tree-sitter AST 지도 | 모델과 사람이 같은 구조를 봄 | 언어별 파서 품질 차이 |
| 경계 유지 | architecture.yml drift 검사 | 무단 의존성 확산 방지 | 규칙 설계 비용 |
| 라우트 파악 | 프레임워크별 핸들러 매핑 | 영향 범위 추정 개선 | 동적 라우팅 한계 |
| 로컬 실행 | 로컬 캔버스와 CLI | 소스 유출 부담 감소 | 설치와 운영 표준화 필요 |
에이전트에게도 유용한 문맥 계층
AI 코딩의 품질은 모델 성능만으로 결정되지 않는다. 어떤 파일을 읽었는지, 어떤 경계를 지켜야 하는지, 변경 영향이 어디까지 가는지가 중요하다. Onboard-CLI 같은 도구는 에이전트에게 "코드베이스 지도"를 제공할 수 있다. 예를 들어 PR을 만들기 전 onboard impact를 실행해 영향 파일을 파악하고, drift를 CI에 걸어 경계 위반을 막는 식이다.
프로젝트의 AI Usage Guidelines는 AI 생성 코드에 대한 책임, 테스트, 보안 검토, 라이선스, PR 투명성을 강조한다. 이는 도구 자체의 메시지와도 맞다. AI를 쓰되, 구조와 책임을 도구로 고정하겠다는 태도다.
한국 개발팀에는 특히 레거시 모듈과 신규 AI 기능이 섞이는 시점에 유용하다. 많은 팀이 "이 파일은 왜 여기서 import하면 안 되는가"를 문서로만 관리한다. 그런 규칙은 신규 입사자와 AI 에이전트 모두에게 잘 전달되지 않는다. architecture.yml처럼 기계가 읽는 규칙으로 옮겨야 지속 가능하다.
경쟁 구도: IDE 플러그인 밖의 코드 인텔리전스
GitHub Copilot, Cursor, Devin, Codex 계열 도구가 코드 편집과 생성에 집중한다면, Onboard-CLI는 코드베이스 인벤토리와 지도 쪽에 가깝다. GitHub의 Tree-sitter 토픽 페이지는 Tree-sitter가 소스 파일의 구문 트리를 만들고 증분 업데이트할 수 있는 파서 생성 시스템이라고 설명한다. 이 기반 위에서 다양한 코드 인텔리전스 도구가 나오고 있다.
다만 Onboard-CLI가 팀 표준이 되려면 세 가지를 증명해야 한다. 첫째, 대형 모노레포에서 충분히 빠른가. 둘째, 시각화가 예쁜 그림을 넘어 실제 리팩터링 결정을 돕는가. 셋째, drift 규칙이 과하게 엄격해 개발 속도를 막지 않는가. 특히 CI에 넣을 때는 fail 조건을 작은 범위부터 시작해야 한다.
자주 묻는 질문
Q1: Onboard-CLI는 AI 코딩 도구인가요?
A: 직접 코드를 생성하는 도구라기보다 코드 구조를 파악하고 시각화하며 아키텍처 경계 위반을 찾는 개발자 도구다.
Q2: 어떤 언어를 지원하나요?
A: README 기준으로 Go, TypeScript, JavaScript, Python, Java 파서를 제공한다고 설명한다.
Q3: 왜 로컬 실행이 중요한가요?
A: 코드베이스 구조와 의존성 정보는 민감할 수 있다. 로컬 분석과 로컬 캔버스는 외부 전송 부담을 줄인다.
Q4: AI 에이전트와 함께 쓰려면 어떻게 시작하나요?
A: 먼저 map과 routes로 구조를 파악하고, architecture.yml을 작게 정의한 뒤 drift를 PR 전 검사로 연결하는 방식이 현실적이다.
Q5: 한계는 무엇인가요?
A: 동적 언어의 런타임 의존성, 프레임워크별 관례, 팀 고유 아키텍처는 자동 분석만으로 완벽히 잡기 어렵다. 규칙과 리뷰가 함께 필요하다.
관련 토픽 더 보기
📰 원본 출처
github.com이 기사는 AI 기술을 활용하여 작성되었으며, 원본 뉴스 소스를 기반으로 분석 및 해설을 추가한 콘텐츠입니다. 정확한 정보 전달을 위해 노력하고 있으나, 원본 기사를 함께 확인하시기를 권장합니다.