<p align="center"><img src="https://raw.githubusercontent.com/AbdulrahmanMasoud/comprende/HEAD/.claude-plugin/icon.png" width="120" alt=""></p>
<h1 align="center">Comprende</h1>
<p align="center"><b>AI가 작성한 코드를 이해하고, 병합(merge) 전에 검증하세요.</b></p>
<p align="center"><a href="README.ar.md">아랍어</a></p>
Comprende는 Claude Code를 위한 플러그인입니다. 이 플러그인은 두 가지 기능을 수행합니다:
- Claude가 작성한 코드를 설명: 간결하고 사용자의 언어로, 설명할 가치가 있는 부분(새로운 API, 명확하지 않은 로직, 위험 요소 등)만 설명합니다. 이는 모든 프로젝트에서 작동합니다.
- 소유권 확인(Ownership check) (선택 사항, 리포지토리별). 코드가 푸시되기 전에 Claude가 해당 코드에 대해 몇 가지 질문을 하고, 사용자가 PR 요약(PR summary)을 작성하게 합니다. 이 과정 없이는 푸시와 병합이 차단됩니다.
<p align="center">
<a href="https://youtu.be/KeoRSyM0zu8"><img src="https://img.youtube.com/vi/KeoRSyM0zu8/maxresdefault.jpg" width="640" alt="Video: Stop Merging AI Code You Don't Understand"></a>
<br>
<a href="https://youtu.be/KeoRSyM0zu8">▶ 시청하기: 이해하지 못하는 AI 코드를 병합하지 마세요</a>
</p>
설치 (Install)
터미널에서 다음 두 명령어를 실행합니다. Node.js 20 이상이 필요합니다.
claude plugin marketplace add AbdulrahmanMasoud/comprende
claude plugin install comprende@comprende
그런 다음 Claude Code를 재시작합니다. 작동 여부를 확인하려면 Claude에서 /mcp를 입력하세요: 목록에 comprende가 있어야 합니다.
이는 모든 프로젝트에 대해 활성화됩니다. 만약 대신 Claude 내부에서 /plugin으로 설치하는 경우, 사용자(user) 범위를 선택하십시오. 프로젝트 범위는 단일 리포지토리에만 활성화합니다.
1. 설명 (Explanations): Claude만 사용하세요
설정할 것은 없습니다. 평소처럼 코드를 요청하면, Claude가 무엇이 새롭거나 명확하지 않거나 위험한지 설명합니다. 실제 답변을 요약했습니다:
당신: 검색창이 키 입력마다 요청을 보냅니다. 사용자가 타이핑을 멈출 때까지 기다리도록 수정해주세요.
Claude: search.js의 검색창에 디바운스(debounce)를 추가했습니다. 이제 키 스트로크마다 요청을 보내는 대신, 사용자가 일시 정지하면 한 번만 요청을 보냅니다.
작동 방식: 각 키 스트로크는 대기 중인 타이머(clearTimeout)를 취소하고 새 타이머를 시작합니다. search() 함수는 300ms 동안 타이핑이 없어야만 실행됩니다.
제가 요청받지 않았지만 추가한 한 가지: 이제 모든 새로운 요청은 AbortController를 사용하여 이전 요청을 취소합니다. …
제가 고치지 않은 보안 문제: r.title이 그대로 innerHTML로 들어갑니다. …
어떤 언어로든 방향을 제시할 수 있습니다:
| 말하기 | 발생하는 일 |
|---|
| "더 설명해줘", "왜?" | 해당 주제에 대해 한 단계 더 깊은 내용 제공 |
| ... | |
Claude는 사용자의 기기 내 ~/.comprende/에 이미 알고 있는 내용을 기억합니다. | |
2. 소유권 확인 (Ownership check)
활성화하기 (팀 리드, 저장소당 한 번)
- 저장소에서 Claude를 열고 다음과 같이 말하세요: "이 저장소의 소유권 게이트(ownership gate)를 활성화해줘."
- Claude는 게이트(
.learning/), CI 체크 및 Claude 훅을 추가하는 PR을 엽니다. .learning/config.json을 검토하는데, 특히 sensitive: 인증(auth)이나 결제(payments)와 같은 경로는 항상 질문을 받게 됩니다. 그런 다음 병합합니다.
- 확인을 필수 항목으로 설정하세요:
node .learning/gate.mjs protect --apply를 실행하거나 Claude에게 요청하세요. 이를 위해 GitHub의 관리자 권한이 필요합니다.
- 팀원들에게 플러그인 설치를 요청하세요. 그들이 할 일은 이것뿐입니다. 저장소에서 첫 세션을 진행하면 나머지는 자동으로 설정됩니다.
사용하기 (모든 개발자)
평소처럼 Claude와 작업하세요. 커밋하거나 푸시하도록 요청하거나, **"나 확인해줘(check me)"**라고 말할 때:
- Claude는 변경 사항에 대해 1개에서 6개의 질문을 한 번에 하나씩 합니다. 작은 변경 사항은 하나의 질문으로 충분합니다.
- 오답에는 간단한 설명이 제공된 후, 다른 질문이 나옵니다.
- PR 요약(summary)은 직접 작성합니다.
- Claude는 보고서를
.learning/checks/에 저장하고, 코드를 커밋하며 푸시합니다.
실제 세션 (요약):
당신: math.js에 add를 사용하여 숫자 목록을 합산하는 sum(xs) 함수를 추가한 후, 커밋하고 푸시해 줘.
Claude: 제가 math.js에 sum을 추가했지만, 아직 아무것도 커밋되지 않았어요. 이 저장소는 소유권 게이트(ownership gate)가 활성화되어 있어서, 커밋 및 푸시 전에 질문 하나에 답하고 짧은 요약을 작성해야 해요. …
질문: 0을 기본값으로 사용하지 않고 sum([])를 실행할 때 xs.reduce(add)는 어떻게 되나요? 왜 그런가요?
당신: 여전히 0이 반환돼요. reduce는 기본적으로 0부터 시작하거든요.
Claude: 정확하지 않아요. reduce에는 기본값으로 0을 설정하는 기능이 없어요. 시작 값이 없으면, 배열의 **첫 번째 요소(first element)**를 시작점으로 사용해요. 빈 배열은 첫 번째 요소가 없기 때문에 오류가 발생합니다. …
같은 아이디어로 하나 더: 만약 0을 기본값으로 사용하지 않는다면요? sum([5])는 무엇을 반환하며, add 함수는 몇 번 호출되나요?
당신: 5를 반환하고, 5가 시작 값이 되기 때문에 add는 한 번도 호출되지 않아요. 요약: sum(xs)를 추가했으며, 이는 add를 사용하여 목록을 합산합니다. 0부터 시작하므로 빈 목록은 오류를 발생시키는 대신 0을 반환합니다.
Claude: sum이 5740db1로 커밋되었고 origin/feature/sum에 푸시되었습니다. … 리포트는 같은 커밋에 포함된 .learning/checks/feature%2Fsum.md에서 확인할 수 있어, CI 체크가 이 코드와 일치할 수 있습니다.
만약 검사를 건너뛰면, Claude는 푸시하지 못하고, git push가 git hook에 의해 차단되며, CI가 PR을 실패시킵니다. 터미널에서 보는 모습은 다음과 같습니다:
In a terminal: a push is blocked, the ownership report is saved, then the push goes through
리드가 확인하는 것
모든 PR마다 소유권 체크(Ownership check) 상태와 함께, 개발자 자신의 말과 각 파일에 대해 설명한 개념 요약이 제공됩니다:
✅ 소유권 검사 통과
개발자 요약
실제 사용자들이 차단되는 문제가 발생하여 공개 API 속도 제한(rate limit)을 분당 IP당 10에서 60으로 상향 조정했습니다. 게이트웨이가 로드 밸런서(load balancer)의 IP만 볼 경우, 이 제한은 전역적(global)이 되므로, 먼저 스테이징 환경(staging)에서 X-Forwarded-For를 확인하십시오.
| 파일 | 개발자가 설명한 개념 |
|---|
src/middleware/rateLimit.js | IP당 슬라이딩 윈도우(sliding window); 윈도우 크기 대 유효 제한; 로드 밸런서 뒤의 X-Forwarded-For |
src/auth/session.js 🔒 | 토큰 만료(token expiry); 새로고침이 일회용인 이유 (why refresh is single-use) |
리드(lead)는 점수, 오답 또는 시도 횟수를 절대 볼 수 없습니다. 목표는 감시가 아니라 소유권입니다.
5분 만에 사용해보기
이 내용을 터미널에 붙여넣으세요. 체크 기능이 활성화된 임시 저장소(throwaway repo)와 GitHub를 대신하는 로컬 폴더를 생성합니다:
mkdir -p /tmp/comprende-try && cd /tmp/comprende-try
git clone -q https://github.com/AbdulrahmanMasoud/comprende.git
git init -q --bare -b main origin.git
...
그런 다음, Claude에서:
- "add a sum(xs) function to math.js using add, then commit and push it" 이라고 말합니다.
- 답변하는 질문에 답합니다. 어떤 일이 발생하는지 확인하기 위해 먼저 오답을 시도해 보세요.
- 한 줄 요약문을 작성합니다. Claude가 보고서를 저장하고 커밋 및 푸시합니다.
더 알아보기
라이선스
MIT
