이 도구가 메우는 간극

대부분의 운영 환경 장애(production incidents)는 명백하게 잘못된 코드 때문에 발생하지 않습니다. 대신, 무언가가 계속 참(true)일 것이라고 조용히 가정하는 (silently assumes) 코드 때문에 발생합니다:

• "이 요청은 단 한 번만 처리된다."
• "마이그레이션(migration)이 워커(worker)보다 먼저 배포된다."
• "해당 API 필드는 절대 누락되지 않는다."
• "이벤트는 항상 순서대로 도착한다."
• "이 레코드는 현재 테넌트(tenant)에 속해 있다."

어떤 AI 코딩 어시스턴트에게든 "이 Diff에서 무엇이 잘못될 수 있을까?"라고 물으면 답변을 얻을 수 있습니다. 문제는 자유 형식(free-form)의 답변은 훑어보기 쉽고, 대충 넘기기 쉬우며, 물어볼 때마다 매번 다르다는 점입니다. 모델이 자신의 작업 과정을 보여주도록 강제하는 표준이 없습니다. 즉, "보호되지 않음(unprotected)"이 실제로 특정 파일과 라인을 지칭해야 한다거나, "심각함(critical)"이 "이거 좀 무서운데"보다 더 구체적인 의미를 가져야 한다는 요구사항이 없습니다.

Assumptions는 그 간극을 메웁니다. 이것은 SKILL.md 파일입니다. 빌드 단계도, 의존성(dependencies)도, 서버도, 계정도 필요하지 않습니다. 에이전트(agent)의 리뷰를 고정된 증거 기반 형식으로 제한합니다:

이것은 에이전트의 판단을 대체하는 것이 아닙니다. 그 판단을 검토하기 빠르고 논리로 회피하기 어려운 형식으로 제한하는 것입니다.

작동 방식

flowchart TD
    subgraph Input ["1. 트리거 및 범위 (Trigger & Scope)"]
        A["Git Diff / PR 변경 사항 (PR Changes)"] --> B["Assumptions 호출 (Invoke Assumptions)"]
...

보고된 모든 결과물은 원장(ledger)에 기록되기 전에 다음 사항을 모두 통과해야 합니다:

보고된 모든 결과물은 원장(ledger)에 기록되기 전에 다음 사항을 모두 통과해야 합니다:

1. **반증 가능한 조건(falsifiable condition)**으로 명시되어야 합니다. (“중복 환불 요청이 방지됨” — “코드가 이상적(idempotent)해 보인다”가 아님).
2. 파일 경로 및 라인 범위로 뒷받침되거나, 라인 범위가 없는 경우 경로 — 심볼이어야 합니다. 요약이나 검색 스니펫에서 라인 번호를 추측하는 일은 절대 없습니다.
3. 가정이 거짓일 경우의 **구체적인 결과(concrete consequence)**가 있어야 합니다.
4. 기존 안전장치(Existing safeguards) — 또는 명시적으로 “X, Y에서는 발견되지 않았으며, Z는 검사하지 않음”이라고 언급해야 합니다.
5. 반증 테스트(falsification test) 또는 검증 단계가 있어야 합니다.
6. 상태(status): Protected / Partially protected / Unprotected / Unknown.
7. 증거 신뢰도(evidence confidence): High / Medium / Low.
8. 우선순위(priority): P0–P3.

상태/신뢰도의 구분은 리뷰어들이 가장 건너뛰는 부분입니다. “Unprotected”는 _리포지토리 내에 안전장치가 존재하는가_를 답합니다. “증거 신뢰도”는 _내가 그 호출에 대해 얼마나 확신하는가_를 답합니다. 핸들러에서 직접 볼 수 있는 누락된 이상적 키(idempotency key)는 Unprotected, High입니다. 미들웨어 파일을 열어보지 않은 상태에서 검사 로직이 누락된 경우, 실제로 보지 않았기 때문에 Unprotected가 아니라 Unknown입니다.

빠른 시작 (Quick start)

mkdir -p .claude/skills/assumptions
cp SKILL.md .claude/skills/assumptions/SKILL.md

그런 다음, 모든 에이전트 세션에서:

Use Assumptions to review the current diff.

이것이 전체 설치 과정이자 전체 호출입니다.

사용자 레벨 설치(User-level install) (모든 프로젝트에서 사용 가능):

mkdir -p ~/.claude/skills/assumptions
cp /path/to/Assumptions/SKILL.md ~/.claude/skills/assumptions/SKILL.md

다른 모든 에이전트 호스트(Any other agent host): 리포지토리를 클론하고 에이전트의 스킬/명령어 설정(skill/instruction config)을 SKILL.md에 지정합니다. 이는 공급업체별 구문이 없는 일반 마크다운 파일입니다 — Claude Code가 참고 통합 사례이지만, 마크다운 명령어 파일을 읽고 리포지토리를 검사할 수 있는 것이라면 무엇이든 사용할 수 있습니다.

호스트가 스킬을 자동 발견하지 못하는 경우, SKILL.md의 내용을 시스템 프롬프트나 사용자 지정 지침 필드에 직접 붙여넣으세요.

사용법 (Usage)

Assumptions를 사용하여 현재 diff를 검토합니다.
Assumptions를 사용하여 src/billing/create-refund.ts를 검토합니다.
Assumptions를 배포 모드(deploy mode)에서 사용합니다: "nullable한 organization_id 컬럼을 추가하고, 백필(backfill)한 다음, 이를 필수 사항으로 만듭니다."
...

호스트가 슬래시 명령어(slash commands)를 등록하는 경우, 동일한 모드는 다음과 같이 매핑됩니다:

/assumptions-scan
/assumptions-scan src/billing/create-refund.ts
/assumptions-scan --deploy "Add a nullable organization_id column, backfill it, then require it"
...

실제 예시 (A real example)

입력: Stripe 환불을 재시도하는 새로운 엔드포인트.

// src/refunds/retry.ts
app.post("/refunds/:id/retry", async (req, res) => {
  const refund = await stripe.refunds.create({
...

멱등성 키(idempotency key)가 없습니다. 호출 전에 기록된 로컬 레코드(local record)가 없습니다. 해피 패스(happy path)만 다루는 하나의 테스트만 존재합니다.

출력된 원장 (P0/P1 행 두 개로 축약):

| 제공자 호출이 성공한 후 응답을 종료합니다; 이후 환불 상태를 확인합니다. | 클라이언트나 백그라운드 작업(background job)이 폴링(poll)할 수 있는 영구적인 환불 요청 기록을 추가합니다. | Medium |

여기에 포함되지 않은 내용에 주목하세요: 모호한 "에러 핸들링 추가를 고려하십시오"와 같은 문구도, 지어낸 비즈니스 규칙도, 해당 파일을 열어본 적이 없으므로 API 게이트웨이가 무엇을 하는지에 대한 주장도 없습니다. 그러한 공백은 잘못된 확신으로 뭉뚱그려지는 대신, 원장(ledger)의 "알 수 없는 사항 및 경계(Unknowns and boundaries)" 섹션에 명시적으로 명명됩니다.

테넌트 간 액세스(cross-tenant access), 안전하지 않은 마이그레이션(unsafe migrations), 웹훅 순서(webhook ordering), 캐시 만료(cache staleness) 등 6개의 전체 원장이 리포지토리의 examples/ 폴더에 있습니다.

가치를 증명하는 부분

의도적으로 지향하지 않는 것

• 일반적인 AI 코드 리뷰어가 아님
• 정적 분석기(static analyzer)가 아님
• 상상 속의 엣지 케이스(edge cases) 목록이 아님
• 자율적인 코드 수정기가 아님 — 사용자가 요청하지 않는 한 코드를 절대 변경하지 않음

또한, 이를 신뢰하기 전에 알아두어야 할 실제적인 한계가 있습니다: 에이전트 호스트(agent host)가 검사할 수 있는 것만 볼 수 있습니다. 큐 전달 의미론(Queue delivery semantics), 게이트웨이 재시도 정책(gateway retry policy), 그리고 제공자의 실제 보장 사항은 리포지토리의 코드, 테스트, 설정 또는 문서에 캡처되지 않는 한 Unknown 상태로 남습니다. Unknown을 리스크가 확인된 부재가 아니라, 검증해야 할 작업으로 취급하십시오.

단순한 느낌(vibes)이 아닌 벤치마크를 통한 검증

이 리포지토리는 소규모 평가 스위트(eval suite)를 제공합니다: 알려진 숨겨진 가정(assumptions)이 포함된 피스처(fixtures)가 포함되어 있으며, 예상 결과 파일(expected-findings file)을 기준으로 블라인드 테스트(blind test)를 거쳐 등급이 매겨집니다.