AI 코딩 에이전트를 위한 오픈소스 아키텍처 가드 출시

AI 요약

코드가 빌드되고 테스트를 통과해도 프로젝트 구조는 나빠질 수 있습니다. 기존 경계를 우회하거나 저장소에 접근하는 경로를 늘리고, 이미 있는 서비스를 중복 구현하는 식입니다. Codapult Guard는 이런 구조적 문제를 찾기 위한 오픈소스 도구입니다.

저장소 구조를 바탕으로 규칙을 검사합니다

Guard는 저장소의 import, AST 관계, 라우트, 기능 권한, Git 이력, 변경 영향 등을 살펴 프로젝트의 구조와 정책을 다룹니다. 팀은 여기서 확인한 내용을 명시적인 규칙으로 정리하고 이후 변경 사항이 규칙을 위반하는지 검사합니다. 작성자는 이 도구를 AI 코드 리뷰어로 만들려는 것이 아니라고 설명합니다. 핵심 검사는 LLM을 호출하지 않으며 로컬에서 동작하고, 특정 모델이나 Codapult 서비스에 의존하지 않습니다.

기존 위반과 새 위반을 구분합니다

오래된 프로젝트에는 이미 아키텍처 규칙을 어기는 코드가 있을 수 있습니다. 전체 저장소를 처음부터 실패 처리하면 검사 게이트를 끄기 쉽습니다. Guard는 현재 발견 사항을 기준선으로 등록하고 새로 생긴 위반을 중심으로 검사합니다. 오류 수준 규칙이나 계약에 해당하는 새 위반은 실행을 실패 처리하고, 경고는 참고 사항으로 남깁니다.

Guard 0.5.0에는 변경 영향에 따른 가드레일, 설명 가능한 검사 결과, 보호된 정책 승인, 실행 출처 기록, 아키텍처 예산, 동시 실행을 고려한 상태 관리, 도구 어댑터, 실행 관측 기능이 추가됐습니다. 전체 프로젝트를 검사하는 기본 모드와 변경 파일만 보는 check --changed가 있습니다. review 명령은 기본적으로 변경 범위를 대상으로 하며, 제한된 diff와 프로젝트 맥락, 계약, 결정론적 검사 결과, 아키텍처 영향을 묶어 검토 자료를 만듭니다. 자동 실행 시점은 호스트 도구에 달려 있습니다. Guard 자체는 에이전트의 작업 종료 시점을 정하지 않습니다.

Indie Hackers 반응

• @omri_ben_shoham — 어려운 점은 위반을 잡는 일이 아니라, “합의한 경계를 깼는지”와 “우리가 몰랐던 경계를 드러냈는지”를 구분하는 일입니다. Guard의 결정론적 검사는 첫 번째를 다룹니다. 하지만 기준선을 만들려면 무엇이 레거시이고 무엇이 실제 아키텍처 제약인지 먼저 결정해야 합니다. 저장소 이력을 보고 “처음부터 잘못됐는지, 경계의 의미를 나중에 바꿨는지” 물어야 하는 측정 문제입니다. 첫날부터 기존 코드 때문에 실패하는 게이트는 꺼집니다. 반대로 미묘한 위반을 조용히 놓치는 게이트는 게이트가 없는 것보다 나빠질 수 있습니다.
• @credolopes — 마지막 문단에 묻힌 내용이 가장 중요합니다. 핵심 검사가 LLM을 호출하지 않는다는 점입니다. 단순히 지연 시간이나 비용 문제가 아니라, 이 검사 방식의 신뢰성과 관련이 있습니다. 변경 사항이 경계를 지키는지 AI 리뷰어에게 물으면 토큰마다 비용을 내는 확률적 답을 받고, 모델 버전이 바뀌면 답도 달라집니다. 결정론적 검사는 오늘과 6개월 뒤에 같은 판정을 내리고 실행 비용도 들지 않습니다. 규칙으로 표현할 수 있는 일은 모델을 빌려 다시 처리하지 말아야 합니다. 기준선도 중요합니다. 첫날부터 레거시 문제로 실패하는 게이트는 일주일 안에 꺼집니다. 기존 위반은 기준선에 넣고 새 위반은 실패 처리해야 도구를 계속 쓰게 됩니다. 어댑터를 늘릴 때 Guard가 저장소 상태를 프롬프트로 요약하기 시작하면, 보호하려던 컨텍스트 예산을 차지하게 되는 점도 지켜봐야 합니다. 저는 Claude Code, Codex, Cursor용 무제한 토큰 게이트웨이 Piramyd 창업자라 결정론적 접근을 선호할 이해관계가 있습니다. Guard는 작업 종료 시 전체 diff를 검사하나요, 파일이 바뀔 때마다 점진적으로 검사할 수도 있나요?
  • @Vlad Zoff — Guard에는 결정론적 모드가 두 가지 있습니다. 기본 검사에서는 전체 프로젝트를 확인하고, check --changed는 변경 파일만 검사합니다. review 명령은 기본적으로 변경 범위에 적용됩니다. 제한된 비식별 diff, 프로젝트 맥락, 계약, 결정론적 검사 결과, 아키텍처 영향을 함께 제공합니다. 에이전트가 작업을 끝낸 뒤 실행하거나 변경 단위 작업 흐름에 쓸 수 있습니다. Guard는 LLM을 호출하거나 호스트가 언제 실행할지 결정하지 않습니다. 자동 Stop 또는 완료 시점 연동은 호스트별 기능입니다. 결정론적 게이트는 LLM 컨텍스트 경로 밖에 두려고 합니다. MCP review 도구는 의미 판단이 필요할 때 외부 AI나 사람이 검토하도록 제한된 자료를 준비합니다. 기본 통과·실패 검사는 모델 없이 동작합니다. 기존 발견 사항은 기준선으로 처리하고 새 오류는 실행을 실패 처리하며, 경고는 참고용으로 남깁니다.
• @flob2025 — 에이전트가 코드를 더 쓰기 전에 아키텍처를 지키는 건 적절한 층위입니다. 제가 우려하는 실패 방식은 부드러운 경고를 띄우고도 PR이 병합되는 상황입니다. 새 경계 위반은 실행을 실패 처리하고 오래된 문제는 기준선으로 두는 편이 좋겠습니다. 규칙 위반 때 실행을 강제로 실패시키나요, 아니면 사람이 무시할 수 있는 보고서만 남기나요?
  • @Vlad Zoff — 오류 수준 규칙이나 계약에 해당하는 새 위반은 실행을 실패 처리합니다. 기존 발견 사항은 기준선에 등록할 수 있고 경고는 참고용입니다. 아키텍처 경계에는 보통 오류 수준 규칙을 쓰고, 사람이 결과를 확인해야 하는 경우에는 경고를 씁니다.
• @mohith808 — 기존 위반을 기준선으로 등록하는 점이 실제 사용에 중요합니다. 첫날부터 레거시 코드 때문에 실패하는 게이트는 일주일 안에 꺼집니다. 도구 어댑터와 관련해 Meta의 Muse Code는 ~/.config/muse/hooks/에 SessionStart, PreToolUse, PermissionRequest, Stop 등의 생명주기 훅을 등록합니다. Guard의 빠른 검사를 Stop 시점에 실행하면 변경 사항을 돌려주기 전에 확인할 수 있습니다. 포크 없이 외부 도구를 연결한 사례도 있습니다.
  • @Vlad Zoff — 그런 검사에는 Stop이 가장 깔끔한 위치일 것 같습니다. 에이전트가 작업을 마친 뒤 결과를 돌려주기 전에 눈에 띄는 문제를 잡을 수 있습니다. Muse의 훅은 자세히 살펴보지 않았지만 적절한 연동 지점으로 보입니다.
• @Luca_Rossi — 기준선과 새 위반을 구분하는 방식은 실제 코드베이스에서 쓰기 좋습니다. 기존 문제를 허용하되 예외가 조용히 영구 정책으로 굳지 않도록 담당자와 사유, 만료 시점을 두는 기능도 있으면 좋겠습니다.
  • @Vlad Zoff — 동의합니다. 기준선이 영구 예외 목록으로 조용히 굳어서는 안 됩니다. 담당자와 사유, 만료 시점을 기록하면 예외를 둔 이유를 잊기 어려워집니다.
• @aryan_sinh — Guard가 새 아키텍처 위반을 잡은 뒤 팀이 실제로 에이전트 작업 흐름을 바꾼 사례가 있나요, 아니면 아직 아이디어에 대한 관심이 주된 도입 동력인가요?
  • @Vlad Zoff — 아직은 아닙니다. 초기 단계라 실제 프로젝트에서 코딩 에이전트를 쓰는 사람들에게 Guard를 알리는 중입니다. 큰 코드베이스에서 사용하기 시작하면 작업 흐름이 어떻게 달라지는지 확인하고 싶습니다.

원문: Indie Hackers / 번역·요약: Trawling