AI가 작성한 코드의 설계 저하를 감지하는 sentrux 정리해 보기
요약
AI 코딩 에이전트 사용 시 발생하는 코드 설계 저하 문제를 해결하기 위한 도구인 sentrux를 소개합니다. sentrux는 코드베이스의 의존 관계와 구조를 분석하여 설계의 건강 상태를 'quality_signal' 점수로 수치화합니다.
핵심 포인트
- AI 코딩 에이전트로 인한 코드베이스 가시성 저하 및 설계 오염 방지
- 모듈성, 비순환성 등 5가지 지표를 통한 설계 품질 수치화
- Rust 기반의 고성능 OSS 도구로 MCP를 통해 AI 에이전트와 연동 가능
- 단순 문법 검사를 넘어 코드베이스 전체의 구조적 건전성 측정
서론
Claude Code, Cursor, Codex와 같은 AI 코딩 에이전트(AI coding agent)를 사용하면 코드를 작성하는 속도는 상당히 빨라지지만, 한편으로는 AI에게 반복해서 수정을 맡기다 보면 다음과 같은 상태가 될 수 있습니다.
- 비슷한 함수가 다른 파일에 계속해서 늘어남
- import의 방향이 엉망이 됨
- 일부 파일만 거대해짐
- 어디서부터 어디까지가 책임(responsibility)인지 알 수 없게 됨
- AI에게 추가 수정을 요청해도 이전에 작성한 코드를 제대로 활용하지 못함
이러한 상황에서는 테스트가 통과되고 타입 에러(type error)가 없더라도, 코드베이스(codebase) 전체의 가시성이 나빠집니다.
이번에 시도해 볼 sentrux는
이 문제에 대해 "코드베이스의 설계상의 건강 상태"를 수치화하는 도구입니다.
공식적으로는 AI 코딩 에이전트를 위한 real-time architectural sensor라고 설명되어 있습니다. 코드베이스를 스캔하여 의존 관계(dependency)나 파일의 편중 등을 통해 quality_signal이라는 0~10000 사이의 점수를 산출합니다.
조사해 본 결과, 일본어 문서가 적었기 때문에 이 기사에서는 sentrux의 개요, 설치, 실제 사용법, AI 코딩과의 조합 방법, 주의사항을 정리해 보고자 합니다.
sentrux란
sentrux는 코드베이스의 설계 상태를 측정하기 위한 OSS(Open Source Software) 도구입니다.
특징으로는
- Rust 제작
- MIT 라이선스
- 단일 바이너리로 동작
- macOS / Linux / Windows 대응
- tree-sitter plugin을 통해 다국어 대응
- 코드베이스를 의존 관계 그래프(dependency graph)로 해석
- 0~10000의
quality_signal을 출력 - MCP를 통해 AI 에이전트로부터 이용 가능
일반적인 Linter나 Formatter는 주로 파일 단위·행 단위의 문제를 봅니다. 예를 들어 ESLint, Biome 등은 구문(syntax), 스타일, 위험한 작성 방식, 미사용 변수 등을 검출합니다.
반면 sentrux가 보고 있는 것은 조금 더 큰 단위에서의 "코드베이스의 형태"입니다.
예를 들어,
- 파일 간의 의존 관계가 복잡해지지 않았는가
- 순환 의존(circular dependency)이 발생하지 않았는가
- 특정 파일만 너무 많은 책임을 떠안고 있지 않은가
- 비슷한 코드가 늘어나고 있지 않은가
- AI가 다음에 변경할 때 망설이게 되는 상태가 되어 있지 않은가
와 같은 점들입니다.
이 부분이 중요한데, sentrux는 "코드가 올바르게 작동하는가"를 보장하는 도구가 아니라, "코드베이스가 지속적으로 변경을 계속할 수 있는 형태를 유지하고 있는가"를 보는 도구입니다.
quality_signal이란
sentrux는 코드베이스의 상태를 quality_signal이라는 0~10000의 점수로 나타냅니다.
공식 문서에서는 quality_signal이 다음 5가지 지표로부터 계산된다고 설명되어 있습니다.
- modularity (모듈성)
- acyclicity (비순환성)
- depth (깊이)
- equality (균등성)
- redundancy (중복성)
각각을 대략적으로 설명하면 다음과 같이 정리할 수 있습니다.
| 지표 | 보고 있는 것 |
|---|---|
| modularity | 모듈이나 파일이 적절히 나누어져 있는가 |
| ... |
공식 문서에 따르면, 이 5가지 지표를 정규화하고 기하 평균(geometric mean)을 취하여 0~10000의 점수로 만듭니다.
quality_signal = (modularity × acyclicity × depth × equality × redundancy) ^ (1/5) × 10000
기하 평균을 사용하고 있다는 점이 흥미롭네요. 요컨대, 어느 하나라도 지표가 극단적으로 나쁘면 전체 점수도 강하게 떨어집니다. 이를 통해 "중복은 적지만 순환 의존투성이"라거나 "파일 크기는 균등하지만 의존 관계가 너무 깊은" 상태 등도 적절하게 검지할 수 있습니다.
사용법은 추후 정리하도록 하겠습니다.
MCP 연동
sentrux는 MCP 연동도 준비되어 있습니다.
공식 문서에서는 MCP를 통해 다음과 같은 도구가 제공된다고 설명되어 있습니다.
| 도구 | 역할 |
|---|---|
| scan | 디렉토리를 스캔하여 quality signal (품질 신호)과 파일 목록을 반환 |
| ... | |
| MCP 연동을 사용하면, AI 에이전트가 스스로 sentrux를 호출하여 변경 전후의 품질 차이를 확인할 수 있습니다. |
sentrux 사용 시 주의사항
sentrux는 편리하지만, 사용 시 주의해야 할 점도 있습니다.
첫째, sentrux는 테스트의 대체재가 아닙니다.
사양대로 동작하는지, 버그가 없는지, 사용자에게 올바른 동작을 하는지는 기존 방식대로 테스트나 리뷰를 통해 확인해야 합니다.
또한, type check (타입 검사)의 대체재도 아닙니다.
TypeScript나 Rust의 타입 시스템이 검출하는 문제와 sentrux가 보는 문제는 별개라는 점에 주의하십시오.
더 극단적으로 말하자면, sentrux의 점수가 높다고 해서 반드시 좋은 설계라고 할 수는 없습니다. 사양을 잘못 이해한 상태에서도 깔끔하게 분할된 코드를 작성할 수 있기 때문입니다.
sentrux가 보고 있는 것은 어디까지나 코드베이스의 설계상의 형태뿐입니다.
따라서 다른 도구들과 병행하여 사용할 때의 위치는 다음과 같을 것입니다.
테스트: 동작이 올바른지 확인
타입 검사: 타입으로서 파탄 나지 않았는지 확인
Lint / Formatter: 국소적인 작성 방식을 통일
sentrux: 코드베이스 전체의 설계 저하를 확인
직접 사용해보고 느낀 점
AI를 이용한 코딩에서는 코드를 작성하는 속도가 빨라지는 반면, 리뷰하는 쪽의 부담이 늘어나는 경우가 많습니다.
특히 곤란한 점은, AI가 언뜻 보기에 그럴싸하게 동작하는 코드를 대량으로 생성한다는 것입니다.
그 자리에서는 동작하더라도, 자세히 살펴보면 책임(responsibility)이 섞여 있거나 기존의 설계 방침을 무시하고 있는 경우가 빈번합니다.
sentrux는 "AI가 변경한 후에 코드베이스의 형태가 나빠지지 않았는가"를 확인하는 센서로서 기능할 것입니다.
특히 다음과 같은 분들에게는 시도해 볼 가치가 있습니다.
- Claude Code나 Cursor에 대규모 변경을 맡기고 있다
- AI에 의한 변경 후의 리뷰 부담이 커지고 있다
- 코드는 동작하는데, 점점 변경하기가 어려워지고 있다
- 순환 의존(circular dependency)이나 거대 파일을 방치하기 쉽다
- CI에 설계 품질 체크를 도입하고 싶다
요약
sentrux는 AI 코딩 시대의 코드베이스 품질을 측정하기 위한 센서입니다.
핵심은 코드가 동작하는지 여부가 아니라, 코드베이스가 계속해서 변경될 수 있는 형태를 유지하고 있는지를 보는 것입니다.
최근의 개발 환경에서는 AI에게 코드를 작성하게 할수록 코드베이스의 저하도 빨라집니다.
AI에 의한 변경을 리뷰할 때는 테스트나 타입 검사뿐만 아니라, 설계상의 변화도 살펴볼 필요가 있습니다.
sentrux는 이를 위한 하나의 선택지가 될 것입니다.
Discussion
AI 자동 생성 콘텐츠
본 콘텐츠는 Zenn AI의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기