# 내 코드와 연결하기 (MCP)

> Specnote의 가장 강력한 점은 실제 코드에 직접 닿을 수 있다는 거예요. Claude Code 같은 AI 도구와 연결하는 법, 그리고 운영 비밀이 서버에 저장되지 않도록 지키는 방식을 안내할게요.

## 왜 코드를 연결하나요

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 설치)](/ko/docs/install-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 도구에서 다시 한 번 "허용"을 눌러 인증을 새로 해 주세요. 토큰 방식이라면 마이페이지에서 토큰이 폐기되지 않았는지 확인하고, 필요하면 새로 발급받으세요.
- **동기화가 너무 느려요.** 첫 전송은 원래 30~60초가 걸립니다. 그 뒤에도 계속 느리다면, 보내는 파일이 많지는 않은지 살펴보세요. 보통 두 번째부터는 바뀐 부분만 보내 5~10초면 끝나요.

더 궁금한 점은 [자주 묻는 질문](/ko/docs/faq)에서 확인하시거나, support@specnote.io로 보내 주세요.

---

Source: https://specnote.io/ko/docs/connect-your-code