내 코드와 연결하기 (MCP)

왜 코드를 연결하나요

Specnote로 테스트를 만들려면 내 AI(Cursor·Claude Code)를 Specnote에 연결해 두어야 해요. 그 AI가 "이거 테스트 만들어 줘"라는 말을 받아 Specnote에 테스트를 만들거든요. 여기에 더해, 원한다면 내 코드(깃허브 저장소)까지 연결할 수 있는데, 그러면 확인이 훨씬 정확해집니다.

코드를 연결하면 세 가지가 눈에 띄게 강해져요.

• 자동 추출이 정확해집니다. AI가 화면 겉모습만 보는 게 아니라 실제 만든 코드 구조를 참고하기 때문에, 테스트와 단계를 더 빈틈없이 정리합니다. (여기서 단계는 "이메일 입력 → 비밀번호 입력 → 가입 버튼 클릭"처럼 흐름을 잘게 나눈 동작 하나하나예요.)
• 영향 분석이 가능해집니다. 기능 하나를 바꿨을 때 어떤 테스트의 어떤 단계가 영향을 받는지 짚어 줍니다. "이번 변경으로 무엇이 깨질 수 있는지"를 미리 가늠할 수 있어요.
• 재검증이 똑똑해집니다. 코드가 바뀐 부분만 골라 다시 확인하므로, 매번 처음부터 전부 검증하지 않아도 됩니다.

두 가지 연결

헷갈리기 쉬운데, "연결"에는 두 종류가 있어요. 하는 일이 서로 달라요.

• (A) 내 AI ↔ Specnote 연결 (MCP) — 평소 쓰는 AI 코딩 도구가 Specnote와 대화하도록 잇는 다리예요. 테스트를 만들려면 반드시 필요합니다. 이때 쓰는 표준 통로가 MCP(Model Context Protocol)인데, AI 도구가 외부 서비스와 안전하게 대화하도록 약속된 통로라고 보시면 됩니다.
• (B) Specnote ↔ 깃허브 저장소 연결 — 내 코드를 Specnote가 읽어 갈 수 있게 잇는 연결이에요. 선택 사항이지만, 연결해 두면 코드를 알아서 최신으로 유지해 줘서 가장 편합니다.

먼저 드리는 보안 약속

코드를 연결한다고 하면 가장 먼저 떠오르는 걱정이 "내 비밀번호나 결제 키까지 넘어가는 거 아냐?"일 거예요. 그래서 약속부터 분명히 말씀드릴게요.

운영 비밀은 먼저 가린 뒤에 보내고, 서버에 그대로 저장하지 않습니다.

코드를 보내기 전에 비밀을 먼저 가린 다음, 가려진 코드만 서버로 보냅니다. 서버는 안전망으로 한 번 더 검사해서 빠진 비밀까지 잡아냅니다.

여기서 운영 비밀이란 실제 서비스를 돌리는 데 쓰는 진짜 열쇠예요. 운영 데이터베이스 비밀번호, 결제 키, 외부 서비스 접근 키 같은 것들이죠. 다만 비밀을 가리는 일은 정해진 패턴을 찾아 바꾸는 방식이라 100%를 장담하긴 어려워요. 그러니 운영 비밀은 코드에 직접 적어 두지 않는 것이 가장 안전합니다. 혹시 남아 있더라도 보내는 쪽과 서버 양쪽에서 한 번씩 더 걸러내도록 설계해 두었어요.

받는 것 · 받지 않는 것

연결했을 때 무엇이 오가는지 한눈에 정리하면 이래요.

받는 것	받지 않는 것
화면 코드 (프론트엔드 — 사용자가 보는 부분)	.env · *.key · *.pem 같은 비밀 파일
서버 코드 (Backend API — 화면 뒤에서 도는 부분)	AWS · OpenAI · Google 같은 외부 서비스 키
코드 구조 분석 결과 (어떤 화면이 어떤 기능과 이어지는지)	결제 키 · 데이터베이스 비밀번호 · 운영 환경변수

받는 것은 "이 앱이 어떻게 생겼고 어떻게 움직이는지"를 이해하는 데 필요한 코드와 구조뿐이에요. 비밀번호나 키 같은 값은 받지 않습니다.

비밀을 지키는 3겹 안전망

비밀이 새지 않도록 세 겹으로 막아요. 한 겹이 놓치더라도 다음 겹이 잡습니다.

1. 1겹 — 비밀 파일 자체를 제외합니다. .env·*.key·*.pem 같은 비밀 파일과 .gitignore에 적힌 파일은 처음부터 읽지 않아요. 파일이 아예 후보에서 빠지는 단계예요.
2. 2겹 — 코드 본문 속 비밀을 가립니다. 코드 안에 실수로 적어 둔 키가 있어도, 14가지 비밀 패턴(외부 서비스 키·결제 키·데이터베이스 접속 정보·인증 토큰 등)을 찾아 가림 표시로 바꾼 뒤에야 전송합니다.
3. 3겹 — 서버에서 한 번 더 검사합니다. 혹시 앞에서 놓친 비밀이 있는지 서버가 안전망으로 다시 훑어 추가로 가립니다. 무언가 추가로 잡히면 "이만큼 더 가렸어요"라고 알려 드려요.

핵심은 가리는 일이 서버에 닿기 전에 먼저 끝난다는 점이에요. 서버는 이미 가려진 코드를 받고, 마지막으로 한 번 더 확인하는 역할만 합니다.

(A) 내 AI 연결하기 — 브라우저 인증 또는 토큰

내 AI 도구를 Specnote에 잇는 방법은 두 가지예요. 둘 중 편한 쪽을 고르시면 됩니다. (Claude Code·Cursor 등 도구별 설치 명령은 내 AI 연결하기 (MCP 설치)에 따로 정리해 두었어요.)

방법 A — 브라우저 인증 (권장). Claude Code 같은 AI 도구에서 한 번만 "허용"을 누르면 끝나요. 토큰을 직접 복사하거나 다룰 필요가 없습니다. 한 번 허용해 두면 30일 동안 자동으로 회전(주기적으로 안전하게 갱신)되어, 그동안 다시 인증하지 않아도 돼요. 토큰을 신경 쓰고 싶지 않은 분께 가장 편한 방식이라 권장합니다.

방법 B — 토큰. 마이페이지에서 토큰을 발급받아 쓰는 방식이에요. 이 토큰은 spnt_로 시작하고, 따로 만료되지 않습니다 — 마이페이지에서 직접 폐기하기 전까지 계속 쓸 수 있어요. 토큰에는 워크스페이스 읽기·추가와 테스트 실행 권한이 함께 담깁니다. CI 같은 자동 환경에서 쓰기 좋아요. 다만 이 토큰은 비밀번호처럼 다뤄 주세요 — 깃(git)에 올리거나 남에게 공유하지 말고, 새어 나간 것 같으면 마이페이지에서 즉시 폐기하세요.

연결하고 나면 AI 도구 안에서 이런 일을 부탁할 수 있어요.

부탁하면	하는 일
테스트 만들기	검토안(PRD)을 정리해 올리고, 내가 승인한 범위대로 테스트를 만듭니다
코드 보내기	지금 상황에 맞는 방법을 알려주고 필요한 준비를 대신 해 줍니다
변경 영향 분석	바뀐 부분이 어떤 테스트에 영향을 주는지 알려줍니다
수정 리포트 받기	검증이 실패했을 때 어디서 왜 멈췄는지 정리해 줍니다
테스트 조회·실행	만든 테스트와 검증 결과를 불러보고, 검증을 다시 돌립니다
테스트 계정·환경 설정	검증에 쓸 테스트 계정과 사이트 주소를 등록합니다
CI 자동 검증 연결	코드 올릴 때마다 자동 검증하도록 워크플로우와 토큰을 만들어 줍니다

(B) 깃허브 저장소 연결하기 — 코드 자동 최신

코드를 계속 최신으로 유지하는 가장 편한 방법은 깃허브 저장소를 연결하는 거예요. 작업실 보드의 테스트 실행 탭에서 [GitHub 연결하기] 버튼을 누르면 시작됩니다.

1. 깃허브 앱 설치. 버튼을 누르면 깃허브의 앱 설치 화면으로 넘어가요. 검증할 저장소를 고르고 설치하면 됩니다. 설치 도중 "이 설치가 정말 본인 것인지" 확인하는 브라우저 인증을 한 번 거쳐요.
2. 연결 완료. 설치가 끝나면 Specnote로 돌아오고, 테스트 실행 탭에 최근 커밋 3개가 표시돼요. 연결됐다는 신호예요.

이 깃허브 앱은 읽기 전용이에요. 코드와 저장소 정보를 읽기만 하고, 여러분 코드를 고치거나 무언가를 올리지 않습니다.

연결해 두면 좋은 점은, 테스트를 만들거나 다시 확인할 때 Specnote가 그 순간 알아서 최신 코드를 가져온다는 거예요. 기본 브랜치에 올라온 코드가 바뀌었으면 바뀐 부분만 조용히 당겨 와 반영합니다. 여러분이 따로 "동기화" 버튼을 누를 필요가 없어요.

예전에는 커밋할 때마다 자동으로 코드를 보내는 방식(커밋 훅)이 있었는데, 지금은 그 방식을 쓰지 않아요. 깃허브를 연결하면 필요한 순간에 알아서 최신 확인을 합니다.

아직 깃허브에 올리지 않은 코드는 어떻게 하나요

깃허브 연결은 올려 둔(push) 코드만 볼 수 있어요. 아직 올리지 않은 작업 중인 코드를 보내는 별도 프로그램은 따로 제공하지 않습니다.

그래서 확인할 코드는 한 번 올려 두시는 것이 좋아요. 그 뒤로는 Specnote가 알아서 최신 상태를 가져갑니다.

내 AI에게 "코드 보내 줘"라고 부탁하셔도 돼요. 그러면 AI가 지금 상황에 맞는 방법을 알려주고, 할 수 있는 준비는 대신 해 줍니다.

코드를 보내는 일은 한 방향이에요. 내 쪽에서 Specnote로 코드를 보내기만 합니다. Specnote가 내 코드를 거꾸로 바꾸는 일은 없어요. 그래서 안심하고 연결하셔도 됩니다.

테스트 전용 시크릿

검증을 하려면 로그인이 필요한 경우가 많아요. 이때 운영 비밀번호를 넣을 필요는 전혀 없습니다. 대신 테스트 전용 시크릿만 따로 등록하시면 돼요. 테스트용 계정이나 샌드박스(연습용 가짜 결제 환경) 키처럼, 새어 나가도 실제 손해가 없는 값들이죠.

등록한 값은 즉시 암호화되어 보관됩니다(KMS라는 전용 보관 장치를 씁니다). 본인만 열어 볼 수 있고, 화면에서 "값 보기"를 눌러도 5초만 보인 뒤 다시 가려져요. 운영 비밀과는 완전히 분리되어 있으니, 테스트에 필요한 최소한의 값만 안심하고 넣으시면 됩니다.

자주 막히는 곳

• 깃허브 연결이 안 돼요. 앱을 설치할 때 검증할 저장소가 설치 대상에 포함됐는지 확인해 주세요. 저장소를 새로 추가했다면 깃허브의 앱 설정에서 접근 권한을 넓혀 주면 돼요.
• 내 AI 연결이 안 돼요. 브라우저 인증이라면 AI 도구에서 다시 한 번 "허용"을 눌러 인증을 새로 해 주세요. 토큰 방식이라면 마이페이지에서 토큰이 폐기되지 않았는지 확인하고, 필요하면 새로 발급받으세요.
• 동기화가 너무 느려요. 첫 전송은 원래 3060초가 걸립니다. 그 뒤에도 계속 느리다면, 보내는 파일이 많지는 않은지 살펴보세요. 보통 두 번째부터는 바뀐 부분만 보내 510초면 끝나요.

더 궁금한 점은 자주 묻는 질문에서 확인하시거나, support@specnote.io로 보내 주세요.