Cursor는 코드를 빠르게 생성합니다. 하지만 이를 검토하는 과정이 병목 현상이 됩니다. 이는 여러분이 느려서가 아니라, 실제 코드베이스에 대해 12개의 정적 분석 스캐너 (static-analysis scanners)가 내놓은 가공되지 않은 결과물이 300개에서 2,000개 사이의 탐지 결과 (findings)로 나타나며, 그 누구도 2,000개의 결과를 검토할 수는 없기 때문입니다. BrassCoders는 AI 어시스턴트가 소비할 수 있도록 구조화된 단일 YAML 파일을 생성함으로써 이 문제를 해결합니다. 이를 Cursor에서 여세요. 그리고 Cursor에게 분류 (triage)를 요청하세요. 몇 분 만에 끝납니다.

왜 Cursor에 결정론적 계층 (Deterministic Layer)이 먼저 필요한가

BrassCoders는 2026년 6월, 12개의 AI 생성 Python 파일들을 대상으로 AI-coder-bug 벤치마크를 실행하여 심어진 12개의 버그 중 11개를 잡아냈습니다. 이는 결정론적 규칙 (deterministic rules)이 적용되는 모든 카테고리에서 프런티어 모델 (frontier model)과 대등한 성능을 보였으며, Bandit과 Pylint가 0점을 기록한 4개의 성능 안티 패턴 (performance anti-patterns)을 잡아냈습니다.

Cursor는 LLM입니다. 빠르고 추론 능력이 뛰어나지만, 패키지 이름을 환각 (hallucinate)하거나, 파일 간 데이터 흐름 (cross-file dataflow) 버그를 놓치고, 부하 상황에서 조용히 성능을 저하시키는 list.insert(0) 안티 패턴을 가끔 놓치기도 합니다. Cursor가 하지 못하는 것은 프롬프트 (prompt) 없이 모든 파일과 모든 커밋을 자동으로 확인하는 것입니다. BrassCoders는 Cursor가 탐지 결과를 확인하기 전에 Bandit, Pylint, Pyre/Pysa, Semgrep, ast-grep, detect-secrets, 그리고 비밀 정보(secrets), 개인정보/PII, AI 패턴 환각, 성능, 콘텐츠 모더레이션, JavaScript/TypeScript를 위한 6개의 커스텀 탐지기를 포함한 12개의 결정론적 스캐너 (deterministic scanners)를 실행합니다. 패턴 스캔은 단순하고 정직합니다. 그것이 핵심입니다.

업무 분담이 중요합니다. BrassCoders는 구조적 마커 (structural markers)를 찾아냅니다. 즉, 문자열 연결로 구축된 SQL 쿼리, 개인 키처럼 보이는 고엔트로피 (high-entropy) 문자열, 종료 조건이 없는 while True 루프 등을 찾아냅니다. Cursor는 이러한 탐지 결과들을 읽고, 문맥 (context)을 적용하여 무엇을 수정할지 결정합니다. coppersun.dev/blog/we-benchmarked-brasscoders-against-a-frontier-model/에 있는 벤치마크 수치는 각 계층이 무엇을 잡아내는지, 그리고 각 계층이 어디에서 실패하는지를 보여줍니다. 각 도구 하나만을 얼마나 신뢰할지 결정하기 전에 이를 읽어보시기 바랍니다.

2단계 워크플로우 (Two-Step Workflow)

BrassCoders는 모든 내용을 .brass/ai_instructions.yaml에 작성합니다. 단 하나의 파일, 단 하나의 명령어로 AI가 소비하기 좋게 구조화되어 있습니다.

1단계: 터미널에서 brasscoders scan .을 실행합니다. 일반적인 Python 프로젝트의 경우 이 과정은 20~40초 정도 소요됩니다. 각 스캐너(scanner)가 완료될 때마다 체크인되는 것을 확인할 수 있습니다. 스캔이 완료되면 프로젝트 루트에 .brass/ai_instructions.yaml 파일이 생성됩니다.

2단계: Cursor에서 .brass/ai_instructions.yaml 파일을 엽니다. 그런 다음 다음과 같이 질문합니다:

"이 파일을 읽고 탐지 결과(findings)를 분류(triage)해줘. 어떤 것을 먼저 수정해야 하는지, 어떤 것이 오탐(false positives)인지 알려주고, 가장 중요한 Critical 항목 상위 3개에 대한 수정안을 작성해줘."

Cursor는 구조화된 YAML을 읽고, 코드베이스의 나머지 부분에서 문맥(context)을 적용하여 순위가 매겨진, 즉시 수정 가능한 결과물을 반환합니다. 스캔, 열기, 분류로 이어지는 전체 루프는 대부분의 프로젝트에서 5분 미만이 소요됩니다.

최상위 수준의 YAML 구조는 다음과 같습니다:

how_to_read_this_file:
  purpose: "분류 및 수정 생성을 위한 AI 소비용 스캔 결과"
  severity_scale: [CRITICAL, HIGH, MEDIUM, LOW, INFO]
...

상단의 how_to_read_this_file 블록은 AI 어시스턴트에게 심각도 척도(severity scale), 신뢰 수준(confidence levels), 그리고 스캐너 출처(scanner provenance)를 안내합니다. Cursor는 이 블록을 가장 먼저 읽습니다. 탐지 결과 목록에 도달할 때쯤이면, Cursor는 HIGH confidence Bandit 탐지 결과가 추측이 아닌 결정론적 규칙 매칭(deterministic rule match)임을 알게 됩니다.

ai_instructions.yaml 파일의 내용

BrassCoders는 심각도와 신뢰도에 따라 순위가 매겨진 탐지 결과를 출력하며, AI 어시스턴트가 소스 파일을 한 줄씩 읽지 않고도 수정 결정을 내릴 수 있을 만큼 충분한 탐지 항목별 문맥(per-finding context)을 제공합니다.

각 탐지 결과에는 다음 정보가 포함됩니다: 발생 스캐너 (Bandit, Pylint, Pyre/Pysa, Semgrep, detect-secrets, 또는 6가지 커스텀 탐지기 중 하나), 심각도 (CRITICAL부터 INFO까지), 신뢰도 (결정론적 매칭의 경우 HIGH, 휴리스틱(heuristic)의 경우 MEDIUM), 파일 경로, 줄 번호, 사람이 읽을 수 있는 제목, 그리고 해당 패턴이 의미하는 바에 대한 설명입니다. 설명은 사람이 아닌 AI 소비자를 위해 작성되었습니다. 즉, 단순히 패턴을 나열하는 것이 아니라 위험 카테고리(risk category)를 명시합니다.

이 YAML은 사람이 검토하기 위한 용도가 아닙니다. 길고, 설계상 반복적이며(모든 탐지 결과가 독립적임), how_to_read_this_file 섹션은 실제로 LLM을 위한 지침처럼 작성되어 있습니다. Cursor는 이 구조화된 컨텍스트(structured context)를 사용하여 라인 단위의 구체성을 갖춘, 즉시 수정 가능한 조언을 생성합니다. 직접 처음부터 끝까지 읽으려고 시도하는 것은 목적에 어긋납니다. Cursor에서 파일을 열고 Cursor가 읽게 하세요.

OSS 코어는 보강(enrichment) 없이 모든 탐지 결과(findings)를 출력합니다. BrassCoders 유료 버전(개발자당 월 $12)은 의미론적 중복 제거(semantic deduplication) 단계를 추가하여, 거의 중복되는 탐지 결과를 통합하고, 관련 이슈를 클러스터링(clustering)하며, README 및 매니페스트(manifest)에서 파생된 프로젝트 시그니처(project signature)를 기준으로 남은 결과들의 우선순위를 매깁니다. coppersun.dev/benchmarks/에 게시된 Django, FastAPI, NodeGoat, PyGoat의 고정된 커밋(pinned commits) 대상 사례 연구에 따르면, 1,500개의 원시 탐지 결과(raw findings)를 생성하는 스캔은 유료 보강 단계를 거친 후 일반적으로 약 300개로 줄어듭니다. 이 수치는 직접 재현해 볼 수 있습니다.

Pre-Commit vs. Cursor Review

BrassCoders는 LLM이 코드에 손을 대기 전에 구조적 버그를 잡아냅니다. Cursor에서 리뷰를 위해 디프(diff)를 열기 전에 먼저 실행하세요.

가장 많은 버그를 잡아내는 워크플로우는 다음과 같습니다: Cursor 리뷰 세션을 시작하기 전에 brasscoders scan .을 실행하세요. .brass/ai_instructions.yaml에 있는 모든 Critical(심각) 또는 High(높음) 탐지 결과는 BrassCoders가 환각(hallucination) 위험 없이 결정론적으로(deterministically) 잡아낸 것입니다. 이것들을 먼저 수정하세요. 그런 다음 Cursor에서 디프를 열고 더 높은 수준의 코드 리뷰를 요청하세요. 그 시점에서 Cursor는 컨텍스트 윈도우(context-window) 상태에 따라 잡을 수도 있고 못 잡을 수도 있는 SQL 인젝션(SQL injection) 마커를 쫓는 것이 아니라, 로직(logic)을 리뷰하게 됩니다.

CI(지속적 통합, Continuous Integration)의 경우에도 동일한 원칙이 적용됩니다. PR(Pull Request)이 병합(merge) 가능해지기 전에 실행되는 파이프라인 게이트(pipeline gate)로 brasscoders scan .을 추가하세요. coppersun.dev/blog/add-brasscoders-to-github-actions/에 있는 GitHub Actions 통합 가이드에서 정확한 단계별 설정 방법을 다룹니다. 여기에는 Critical(심각) 등급의 결과가 발견되면 빌드를 실패시키고, Medium(중간) 등급은 통과시키도록 심각도 임계값(severity threshold)을 설정하는 방법이 포함되어 있습니다. 해당 게이트 이후에 Cursor AI 리뷰가 수행될 때, AI는 이미 결정론적 스캐닝(deterministic scanning)을 통과한 코드를 리뷰하게 됩니다.

패턴은 다음과 같습니다: 결정론적(deterministic)인 것을 먼저, 추론(reasoning)을 나중에 수행하는 것입니다. BrassCoders는 프롬프트 없이 어디에서나 자동으로 실행됩니다. Cursor는 사용자가 요청할 때 전체 컨텍스트(context)를 바탕으로 추론합니다. 두 도구는 서로를 대체하는 것이 아닙니다.

지금 바로 BrassCoders를 설치(pip install brasscoders 후 brasscoders scan .)하고, Cursor에서 .brass/ai_instructions.yaml 파일을 여세요. coppersun.dev/install/에 있는 설치 가이드를 통해 10분 이내에 설정, 활성화 및 첫 번째 스캔 과정을 완료할 수 있습니다.