BrassCoders와 AI 어시스턴트를 활용하면 500줄 규모의 AI 생성 Pull Request (PR) 검토에 소요되던 45~60분의 시간을 약 10분의 집중적인 작업 시간으로 단축할 수 있습니다. 이 패턴은 명확하게 정의되어 있습니다: 로컬에서 스캔하고, 순위가 매겨진 YAML 파일을 AI 어시스턴트에게 전달하며, 각 발견 사항을 제안된 diff (차이점)와 대조하며 검토한 뒤, diff를 승인하는 방식입니다. 전체 검토 시간은 기반이 되는 PR이 100줄이든 1000줄이든 관계없이 거의 일정하게 유지됩니다.

이 포스트에서는 구체적인 작업 예시를 통해 워크플로우(workflow)를 처음부터 끝까지 살펴보고, 왜 동일한 접근 방식이 Claude Code, Cursor, Continue, Aider에서 모두 작동하는지, 그리고 BrassCoders가 동의하기 어려운 발견 사항을 제시했을 때 어떻게 해야 하는지를 다룹니다.

AI Diff를 한 줄씩 검토하는 방식이 확장 불가능한 이유

BrassCoders가 측정한 한 줄씩 AI-PR을 검토할 때의 실패 모드(failure mode)는 다음과 같습니다: 시니어 엔지니어가 500줄의 diff를 검토하는 데 한 시간을 소비해도, 신호 대비 잡음 비율(noise-to-signal ratio)이 관련 정보를 압도하기 때문에 실제 버그를 놓치게 됩니다. 해결책은 더 많은 근면함이 아니라, 검토 단위(review unit)를 바꾸는 것입니다.

수식은 간단합니다. 500줄 규모의 AI 생성 diff에는 일반적으로 검토할 가치가 있는 3050개의 변경 사항(실제 리팩토링, 실제 새로운 로직)과 나머지 400450줄의 기계적인 후속 작업(포맷터 실행, import 재구성, 주석 추가, 타입 어노테이션(type-annotation) 변동)이 포함됩니다. 한 줄씩 검토하는 방식은 검토자가 중요한 30~50개를 찾기 위해 500줄 전체를 읽도록 강제합니다. 지루한 400줄을 훑어보는 과정에서 발생하는 인지적 비용이 바로 실패 모드를 유발합니다. 300번째 줄에 도달하면 검토자는 빠른 스캔 모드로 전환되며, 312번째 줄에 숨어 있던 단 하나의 실제 버그가 7개의 지루한 포맷터 변경 사항과 함께 무시되어 버립니다.

데이터가 말해주는 것: BrassCoders가 발표한 benchmarks는 9개의 오픈 소스 코드베이스에서 "스캐너가 배출한 원시 발견 사항(raw findings)" 대비 "강화 후 실행 가능한 발견 사항(actionable findings)"의 비율을 측정하며, 전형적인 비율은 5~7배입니다. 500줄의 diff의 경우, 이는 약 47개의 원시 스캐너 발견 사항이 AI 검토자(또는 인간)가 실제로 검토해야 할 12개의 핵심 이슈로 줄어든다는 것을 의미합니다.

아키텍처의 변화: 리뷰어에게 500줄짜리 diff 안에서 12개의 발견 사항을 찾도록 요청하는 것을 멈추세요. 대신, 그들에게 12개의 발견 사항 자체를 직접 전달하세요. 500줄짜리 diff는 작업 단위가 아니라 맥락의 산출물이 됩니다.

BrassCoders 워크플로우 3단계

BrassCoders가 권장하는 워크플로우는 세 단계로 구성됩니다: 스캔(scan), 전달(hand off), 반복(iterate). 스캔은 .brass/ai_instructions.yaml 파일을 생성하고, 전달은 해당 파일을 가리키는 AI 어시스턴트에게 보내는 단일 프롬프트이며, 반복은 각 발견 사항을 제안된 diff로 검토하고 인간 리뷰어가 승인하는 과정입니다.

1단계: 스캔(scan). 리포지토리 루트에서 brasscoders scan . (또는 brasscoders scan path/to/project)를 실행합니다. OSS 코어는 외부 네트워크 호출을 전혀 하지 않으며, 유료 플랜은 이미 마스킹된 발견 사항(출처가 아님)을 게이트웨이로 보내 의미론적 중복 제거 및 재순위 지정 작업을 수행합니다. 결과물은 .brass/에 저장됩니다. AI 전달에 필요한 관련 파일은 짧고 순위가 매겨진 요약 파일인 .brass/ai_instructions.yaml입니다.

2단계: AI 어시스턴트에게 전달(hand off). 작동하는 프롬프트 템플릿은 다음과 같습니다:

"이 프로젝트의 .brass/ai_instructions.yaml 파일을 읽으세요. critical_issues의 각 항목을 순서대로 처리하세요. 각각에 대해, 언급된 라인의 파일을 읽고 주변 코드를 고려하여 해당 발견 사항이 실제인지 아니면 오탐지(false positive)인지 판단하고, 실제라면 diff를 제안하세요. 확신할 수 없다면 인간 검토용으로 표시하고 다음 항목으로 넘어가세요."

Claude Code, Cursor, Continue, Aider 모두 파일 시스템 접근 권한을 가지고 있어 복사-붙여넣기 없이 YAML 파일을 직접 읽습니다. AI는 발견 사항들을 순차적으로 처리합니다.

3단계: 반복(iterate). AI는 각 중요 이슈를 제안된 diff와 함께 제시합니다. 사용자는 이 diff를 검토하고(원래 500줄 PR을 검토하는 것보다 훨씬 빠릅니다. 왜냐하면 각 diff가 작고 목표 지향적이기 때문입니다), 승인하거나 거부한 후 다음 항목으로 넘어갑니다. AI가 불확실하다고 표시한 이슈는 인간만 검토합니다. 회귀(regression)가 없는지 확인하려면 수정 사항 적용 후 brasscoders scan을 다시 실행하세요.

일반적인 500줄 규모의 PR에 소요되는 총 경과 시간: 스캔(scan) 약 10초, AI가 주요 이슈(critical issues)를 검토하는 데 약 23분, 인간이 제안된 차이점(diffs)을 검토하는 데 약 510분. 한 줄씩 읽으며 고군분투하는 4560분 대신, 약 1015분의 집중적인 작업만 필요합니다.

ai_instructions.yaml에는 무엇이 들어있는가

BrassCoders의 ai_instructions.yaml은 AI 소비자(consumer)가 보는 스캔 결과물입니다. 이는 AI 어시스턴트가 코드베이스를 분류(triage)하는 데 필요한 키(keys)를 포함하는 짧고 순위가 매겨진 파일입니다(원시 스캐너 출력물이 3,00010,000줄인 것에 비해 보통 100500줄 정도입니다). 이 형식은 릴리스 전반에 걸쳐 안정적이므로, AI 도구들이 그 구조를 신뢰할 수 있습니다.

최상위 키(top-level keys):

project: brasscoders
scanned_at: 2026-05-31T14:23:17Z
brass_version: 2.0.4
...

critical_issues 리스트는 AI 소비자가 집중하는 부분입니다. 이는 심각도(severity)와 프로젝트 시그니처 관련성(project-signature relevance)에 따라 가장 높게 순위가 매겨진 결과물로, 수정을 놓쳤을 때 실제적인 결과(consequence)를 초래할 수 있는 항목들입니다. critical_issues 아래에는 심각도가 낮은 리스트(security_findings, privacy_findings 등)가 있으며, AI 소비자는 이를 기회가 될 때 처리하거나 건너뛸 수 있습니다.

how_to_read_this_file 필드는 모든 BrassCoders YAML 상단에 위치하는 문자 그대로의 지침 블록(instruction block)입니다. 이는 AI 소비자에게 파일의 나머지 부분을 어떻게 해석해야 하는지 알려줍니다. 이것이 바로 핵심적인 세부 사항입니다. BrassCoders는 AI가 형식을 알고 있다고 가정하지 않습니다. 대신 각 섹션이 무엇을 의미하는지, 우선순위 순서가 무엇인지를 AI에게 명시적으로 알려줍니다. 그 결과 Claude Code, Cursor, Continue, Aider 모두 동일한 지침 블록을 읽기 때문에, 이들 도구 전반에서 일관된 분류(triage) 동작이 나타납니다.

실제 사례: 500줄 규모의 AI 생성 리팩터링

BrassCoders는 Flask 핸들러의 대표적인 500줄 규모 AI 생성 리팩터링(refactor)을 8초 만에 스캔하며, 47개의 원시 결과(raw findings) 중 12개의 critical_issues를 생성합니다. 후속 AI 소비자(이 예시에서는 Claude Code)는 각 이슈를 발견당 2분 미만으로 검토합니다.

설정 단계. 개발자가 Claude Code에게 명확성을 위해 기존 Flask 요청 핸들러(request handler)를 리팩터링(refactor)해달라고 요청합니다. Claude Code는 500줄 전체 파일을 다시 작성합니다. 헬퍼 함수(helper functions)를 추출하고, 타입 어노테이션(type annotations)을 추가하며, 지원 중단된(deprecated) 라이브러리 호출을 교체하고, 에러 핸들링(error handling)을 추가하고, black으로 포맷팅(reformat)합니다. 이 PR(Pull Request)은 500줄의 diff(차이점)를 포함합니다. BrassCoders가 없다면, 리뷰어는 500줄 전체를 한 줄씩 읽어야 했을 것입니다.

스캔 단계. 저장소(repo)에서 brasscoders scan .을 실행합니다. 출력 결과:

Scanning project (12 scanners)...
✓ bandit            42 raw findings
✓ pylint            18 raw findings
...

전달 단계. Claude Code 세션을 열고 다음 내용을 붙여넣습니다:

".brass/ai_instructions.yaml 파일을 읽으세요. critical_issues에 있는 각 항목을 순서대로 처리하세요. 각 항목에 대해, 명시된 라인의 해당 파일을 읽고, 주변 코드를 고려했을 때 해당 발견 사항이 실제 문제인지 아니면 오탐(false positive)인지 결정하세요. 실제 문제라면 diff를 제안하세요. 확실하지 않다면 사람이 검토하도록 표시하고 다음으로 넘어가세요."

Claude Code는 YAML 파일을 읽은 후 12개의 이슈를 하나씩 살펴봅니다. 첫 번째 발견 사항은 47번 라인의 AWS 액세스 키(access key)입니다. Claude는 키를 환경 변수(environment variable)로 옮기는 diff를 제안합니다. 두 번째는 리팩터링 과정에서 요청 파라미터(request parameter)를 쿼리 문자열(query string)에 삽입하여 발생한 SQL 인젝션(SQL injection) 싱크(sink)입니다. Claude는 파라미터화(parameterizing)를 제안합니다. 세 번째는 python -O 실행 시 제거되는 assert를 사용한 입력 검증(input validation)입니다. Claude는 명시적인 예외(explicit exception)를 발생시키도록 제안합니다. 이런 식으로 계속 진행됩니다.

결과. 3분 만에 Claude Code는 11개의 diff를 제안하고 1개의 발견 사항을 불확실한 것으로 표시했습니다. 리뷰어는 제안된 11개의 diff(각각 3~15줄로 읽기 쉬움)를 훑어보며 승인 또는 거절을 결정하고, 불확실한 1개의 발견 사항은 직접 확인합니다. 스캔, AI 검토, 사람의 승인을 모두 포함하여 총 소요 시간은 약 10분입니다.

검토자가 하지 않아도 되었던 일: 리팩터링된 500줄의 코드를 읽는 일입니다. 스캔을 통해 중요한 12가지 사항이 드러났고, Claude Code가 문맥(Context)에 따라 이를 분류(Triage)했으며, 사람이 제안된 차이점(Diffs)을 검증했습니다. AI의 검토 정밀도가 높은 이유는 입력값이 개방형(500줄의 Diff)이 아니라 제한적(12개의 결정론적 발견 사항)이었기 때문입니다.

Cursor, Continue, Aider에서도 동일하게 작동합니다

BrassCoders의 YAML 출력물은 파일 시스템에 상주하는 일반 텍스트이므로, 파일 읽기 기능이 있는 모든 AI 어시스턴트가 이를 사용할 수 있습니다. 동일한 워크플로우가 Cursor, Continue, Aider, Claude Code에서 동일하게 실행되며, 유일한 차이점은 각 도구가 기대하는 프롬프트(Prompt) 문구뿐입니다.

네 가지 주요 옵션은 모두 일급(First-class) 파일 읽기 기능을 갖추고 있습니다: Cursor, Continue, Aider, 그리고 Anthropic의 Claude Code CLI입니다. 팀에서 이미 사용 중인 도구를 선택하세요. 근간이 되는 BrassCoders 워크플로우는 동일합니다.

Cursor: 동일한 프롬프트 템플릿을 사용합니다. Cursor의 Composer는 @ 참조를 통해 로컬 파일을 읽을 수 있습니다. Composer에 프롬프트를 붙여넣고 @.brass/ai_instructions.yaml을 참조하면 AI가 해당 파일을 문맥(Context)으로 로드합니다.

Continue: 동일한 프롬프트 템플릿을 사용합니다. Continue의 @file 슬래시 명령어가 동일한 역할을 수행합니다. 전체 분류(Triage) 사이클이 일련의 작은 @file 범위 작업으로 이루어지기 때문에, 이 워크플로우는 Continue의 슬래시 명령어 기반 UI와 잘 통합됩니다.

Aider: 동일한 프롬프트 템플릿을 사용합니다. Aider는 명시적인 파일 목록을 기반으로 작동하므로, /add .brass/ai_instructions.yaml 명령어로 .brass/ai_instructions.yaml을 문맥에 추가하세요. Aider의 '변경 후 즉시 커밋(Commit-after-each-change)' 흐름은 '발견 사항에 대한 반복(Iterate-on-findings)' 패턴과 잘 어울립니다.

네 가지 도구 모두에서 동일한 점은 YAML이 제약 조건(Constraint) 역할을 한다는 것입니다. AI는 무제한적인 Diff를 대상으로 작업하는 것이 아니라, 순위가 매겨진 발견 사항 목록을 대상으로 작업합니다. 분류(Triage) 시간은 기반이 되는 PR의 크기가 아니라 발견 사항의 개수에 따라 결정됩니다.

네 가지 도구 모두에서 차이점이 발생하는 지점은 다음과 같습니다: 각 도구가 제안된 차이점(diffs)을 어떻게 드러내는지, 각 도구가 변경 사항을 어떻게 커밋(commit)하는지, 그리고 각 도구가 불확실성을 어떻게 처리하는지입니다. 이것들은 워크플로의 근본(fundamentals)이 아니라 워크플로의 인체공학(ergonomics)에 해당합니다. 팀이 이미 사용 중인 어시스턴트를 선택하십시오. BrassCoders는 내부적으로 동일한 방식으로 작동합니다.

단일 500줄짜리 PR(Pull Request)에서 절약되는 리뷰어의 시간은 대략 35~50분입니다. 하루에 여러 개의 AI 보조 PR을 배포하는 활발한 팀 전체로 이 수치를 곱하면, 절약된 시간은 집중력을 회복할 수 있는 오후 시간 전체로 복리로 쌓이게 됩니다.

pipx install brasscoders 명령어로 BrassCoders를 설치하고, 다음 AI 생성 PR에서 이 워크플로를 시도해 보세요. AI 코드 리뷰의 실패 모드(failure modes)에 대한 더 넓은 맥락은 AI Code Review: The Practical Guide for 2026를 참조하십시오.