BrassCoders는 매 스캔 후에 .brass/ai_instructions.yaml 파일을 작성합니다. 이 파일은 AI 어시스턴트가 코드베이스를 처음부터 추측하는 대신 읽어들이는 파일입니다. 각 탐지(finding) 항목에는 심각도(severity) 수준, 파일 경로, 줄 번호(line number), 그리고 수정 사항(remediation note)이 포함되어 있습니다. Claude Code나 Cursor에게 동일한 코드베이스를 검토하도록 요청하는 채팅 프롬프트(chat prompt)에는 이러한 속성이 전혀 없습니다. 즉, 지속적인 상태(persistent state), 줄 고정(line anchors), 도구가 예상하도록 설계된 형식이 존재하지 않습니다.

그 격차가 바로 findings file이 존재하는 이유입니다.

.brass 파일에 실제로 포함된 내용

BrassCoders는 스캔된 프로젝트 디렉토리에 .brass/ai_instructions.yaml 파일을 생성합니다. 각 탐지 항목은 id, 심각도(critical, high, medium, low 또는 info), 파일 경로, 줄 번호, 그리고 수정 방향을 설명하는 remediation 필드를 나열합니다. 이 파일은 작성하기 전에 심각도에 따라 탐지 항목을 정렬하므로, 어떤 파일에서 나왔는지와 관계없이 critical 심각도 항목이 가장 먼저 나타납니다.

대표적인 탐지 항목은 다음과 같습니다:

issues:
  - id: bandit-B608-001
    severity: critical
...

에디터의 AI 어시스턴트는 이를 작업 큐(work queue)로 읽습니다. 심각도는 검토 순서를 제공합니다. 파일 경로와 줄 번호는 소스 코드에 고정(anchor)해 줍니다. remediation 필드는 코드를 단 한 줄도 읽기 전에 수정 방향을 제공합니다.

채팅 프롬프트가 초기화되는 이유

BrassCoders의 findings file은 스캔 사이에도 디스크에 지속적으로 유지되며, 탐지된 항목이 수정되고 스캔을 다시 실행할 때만 줄어듭니다. 반면, 채팅 기반의 코드 리뷰 세션은 매번 빈 상태로 시작됩니다.

Claude Code나 Cursor의 새로운 채팅 세션에서 AI 어시스턴트는 어제 무엇을 발견했는지에 대한 기억이 없습니다. 사용자는 코드베이스를 다시 설명하고, 컨텍스트(context)를 다시 진술하며, 무엇을 찾아야 하는지 다시 지정해야 합니다. 모델이 이번에 다르게 샘플링한다면, 탐지 결과가 다른 순서로 나타나거나, 이름이 달라지거나, 혹은 완전히 누락될 수도 있습니다. findings file은 이러한 변수들을 상수(constants)로 다시 씁니다. 파일은 무엇이 발견되었는지 말해주고, AI 어시스턴트의 역할은 그것을 확인하고 수정하는 것입니다.

이것은 규모가 커질수록 더욱 중요해집니다. 수십 개의 모듈에 걸쳐 500개의 Python 파일로 구성된 코드베이스는 채팅 프롬프트(chat prompt)가 신뢰할 수 있게 추론하기에는 너무 많은 발견 사항(findings)을 생성합니다. BrassCoders가 발표된 코퍼스 내 15개의 AI 생성 파일에서 찾아낸 53개의 발견 사항은 일일이 설명할 필요가 없습니다. 그것들은 이미 파일 안에 정렬되어 있고, 줄 번호(line numbers)와 함께 분류(triage)되기를 기다리고 있습니다.

AI 어시스턴트가 파일을 사용하는 방식

BrassCoders는 파일을 작성하기 전에 발견 사항의 심각도(severity)를 우선하여 정렬합니다. 따라서 심각한 SQL 인젝션(SQL injection)이 중간 수준의 스타일 노트보다 상단에 나타납니다. Claude Code는 이러한 순서를 읽고, 별도의 지시 없이도 가장 심각도가 높은 발견 사항을 먼저 분류합니다.

정렬 외에도, 줄 번호는 AI 어시스턴트가 소스 컨텍스트(source context)를 가져오는 방식을 변화시킵니다. 줄 참조(line reference)가 없다면, 모델은 파일 전체를 읽고 어디가 잘못되었을지 추론해야 합니다. 하지만 줄 번호가 있으면, 모델은 플래그가 지정된 위치로 직접 점프하여 그 주변의 좁은 코드 창(code window)을 읽고, 해당 발견 사항이 실제인지 판단합니다. 이것이 실제 BrassCoders와 Claude Code의 분업 방식입니다: BrassCoders는 줄을 식별하고, Claude Code는 컨텍스트를 판단합니다.

remediation(수정) 필드는 한 단계의 층을 더 추가합니다. "? 또는 %s 플레이스홀더(placeholder)를 사용하는 매개변수화된 쿼리(parameterized query)로 별도의 값 튜플(values tuple)과 함께 교체하십시오"라고 말하는 발견 사항은 AI 어시스턴트에게 구체적인 수정 방향을 제공합니다. AI는 제1원리(first principles)로부터 올바른 패턴을 발견할 필요가 없습니다. 수정 사항을 읽고, 플래그가 지정된 줄을 확인한 뒤, 수정 사항을 생성하거나 해당 발견 사항을 오탐(false positive)으로 기각합니다. 대화는 발견이 아닌 확인에서 시작됩니다.

오프라인 보장

BrassCoders의 오픈 소스 코어는 brasscoders --offline scan으로 실행되며 기기 외부로 단 1바이트도 전송하지 않습니다. 발견 사항 파일은 로컬에 작성되고 로컬에서 읽히며, 유료 플랜의 인리치먼트(enrichment) 패스를 실행하지 않는 한 절대 전송되지 않습니다.

AI 리뷰어는 호출될 때마다 사용자의 소스 코드를 외부 API로 전송합니다. 데이터 처리 규칙이 적용되는 모든 코드베이스 — 내부 도구, 금융 기록, 의료 데이터, 보안 정책에 의해 플래그(flag)가 지정될 수 있는 모든 코드 — 의 경우, 오프라인 경로만이 정책 예외 없이 모든 커밋(commit)에서 실행될 수 있는 유일한 방법입니다. Findings File은 소스 코드가 기기를 떠나지 않고도 중요한 사항들을 포착합니다.

AI가 생성한 코드를 검토하기 위한 GitHub 자체 가이드라인은 개발자들에게 "항상 자동화된 테스트와 정적 분석 도구를 먼저 실행하고">(https://docs.github.com/en/copilot/tutorials/review-ai-generated-code) 모델 리뷰를 얹기 전에 코드 스캐너를 실행할 것을 권장합니다. BrassCoders는 모든 푸시(push) 시 오프라인에서 가장 먼저 실행되는 스캐너입니다. AI 리뷰어는 그 위에 얹어서 사용하는 도구입니다.

워크플로우에 연결하기

BrassCoders는 단 하나의 명령어로 findings file을 작성합니다: brasscoders --offline scan /path/to/project. 이 스캔은 Python 코드베이스 전반에 걸쳐 12개의 정적 분석(static-analysis) 스캐너를 실행하고, 프로젝트 디렉토리에 .brass/ai_instructions.yaml 파일을 작성합니다. 동일한 디렉토리에서 Claude Code 또는 Cursor를 열면 해당 파일이 프로젝트 컨텍스트(context)로 사용 가능해집니다.

워크플로우: 에디터를 열기 전에 스캔하십시오. AI 어시스턴트가 분류한 고위험(high-severity) 발견 사항들을 검토하십시오. 실제 문제인 것을 수정하십시오. 발견 사항이 사라졌는지 확인하기 위해 다시 스캔하십시오. 대부분의 Python 코드베이스에서 각 스캔은 몇 초 내에 완료됩니다. Findings File은 코드 리뷰 채팅의 "문제를 설명하는" 단계를, 어시스턴트가 이미 읽는 법을 알고 있는 구조화된 아티팩트(artifact)로 대체합니다.

pip install brasscoders
brasscoders --offline scan /path/to/your/project