문제 해결

문제가 생기면 당황하지 말고, 해당하는 증상을 찾아 위에서부터 차례로 짚어 보세요. 여기 없는 문제라면 언제든 support@specnote.io로 보내 주시면 됩니다 — 화면 오른쪽 아래 채팅으로 물어보셔도 돼요.

내 AI가 Specnote에 연결되지 않아요

증상: AI에게 "테스트 만들어 줘"라고 해도 Specnote를 못 찾거나, "인증 실패"라고 나와요.

1. 연결 자체가 안 되어 있는 경우 — Claude Code라면 /mcp를 입력해 목록에 specnote가 있는지 확인하세요. 없다면 내 AI 연결하기 (MCP 설치)의 설치 단계부터 다시 진행하면 됩니다.
2. 브라우저 인증이 만료된 경우 — /mcp에서 specnote를 골라 "허용"을 다시 눌러 주세요. 인증은 30일 동안 자동 갱신되지만, 오래 안 쓰면 만료될 수 있어요.
3. 토큰이 폐기된 경우 — 마이페이지의 MCP 연결에서 토큰이 살아 있는지 확인하세요. 폐기됐다면 새로 발급받아 설정의 토큰 값을 바꿔 주면 됩니다.
4. 도구를 재시작 안 한 경우 — 설정을 바꾼 직후라면 AI 도구를 한 번 껐다 켜 보세요. 설정을 다시 읽으면서 연결되는 경우가 많아요.

테스트 만들기가 진행되지 않아요

증상: AI가 테스트를 만들다 말거나, "환경이 없다"는 안내가 나와요.

1. 테스트할 주소가 등록 안 된 경우 — 테스트를 만들 때 Specnote가 실제 화면을 둘러보며 단계를 채우기 때문에, **테스트 환경(사이트 주소)**이 먼저 필요해요. 테스트 환경과 계정 설정을 보고 주소부터 등록해 주세요.
2. 어느 워크스페이스인지 애매한 경우 — 워크스페이스가 여러 개라면 "워크스페이스는 ○○야"라고 함께 말해 주세요.
3. 크레딧이 부족한 경우 — AI가 앱을 둘러보는 작업은 크레딧을 써요. 크레딧과 요금제에서 잔액을 확인하고 필요하면 충전해 주세요.

검증이 시작되지 않아요

증상: 테스트 실행을 눌러도 검증이 돌지 않거나 바로 실패해요.

1. 크레딧 부족 — 검증을 시작하려면 잔액이 1크레딧 이상 있어야 해요. 잔액이 그보다 적으면 그 회차는 실행되지 않으니, 부족하면 충전해 주세요.
2. 사이트 주소에 접속이 안 되는 경우 — 등록한 주소를 브라우저에서 직접 열어 보세요. 접속되지 않는 주소라면 Specnote 서버도 열 수 없어요. 주소가 바뀌었다면 테스트 환경에서 새 주소로 고쳐 주세요.
3. localhost 주소인 경우 — 내 PC에서만 도는 주소는 서버가 접속할 수 없어요. 환경을 내 컴퓨터(LOCAL) 방식으로 등록해 주세요. 방법은 테스트 환경과 계정 설정에 있어요.

검증 묶음이 시작되지 않고 "PRD 승인 후에만" 안내가 나와요

증상: 새 검증 묶음을 시작하려는데 검증이 바로 돌지 않고, 검토안(PRD)을 먼저 승인하라는 안내가 떠요.

이건 오류가 아니라 정상 동작이에요. 새 검증 묶음은 "무엇을 어떤 규칙으로 검증할지" 정리한 기획 검토안(PRD)을 사람이 한 번 승인한 뒤에만 시작됩니다. 흐름은 이래요.

1. AI에게 "이 워크스페이스 검증 묶음 시작해 줘"라고 부탁하면, AI가 검토안(PRD)을 정리해 와요.
2. 실행 묶음 화면의 PRD 검토에서 규칙을 훑어보고 승인해요. (본인이 AI에게 "승인해 줘"라고 명시하면 AI가 대신 눌러 줄 수도 있어요.)
3. 승인되면 테스트가 제출되고 첫 검증이 자동으로 돌기 시작해요.

참고로 이미 만든 테스트를 다시 검증하거나 실패한 것만 재실행하는 건 이 승인 없이 그대로 돼요. 검토안 승인은 "새 검증 묶음을 처음 시작할 때"만 거치는 관문이에요. 자세한 내용은 검증 돌리고 결과 읽기를 봐 주세요.

로그인 단계에서 자꾸 실패해요

증상: 검증이 로그인 화면 근처에서 반복해서 막혀요.

1. 테스트 계정이 없는 경우 — 회원 흐름을 검증하려면 로그인할 계정이 등록되어 있어야 해요. 테스트 환경 탭의 로그인 계정을 확인해 주세요.
2. 계정 정보가 틀렸거나 만료된 경우 — 등록해 둔 계정으로 실제 사이트에 직접 로그인해 보세요. 비밀번호가 바뀌었거나 계정이 잠겼다면 새 정보로 다시 등록하면 됩니다.
3. 환경과 계정이 어긋난 경우 — 계정은 환경마다 따로예요. 스테이징 계정으로 운영 주소에 들어가려 하고 있지 않은지 확인해 주세요.
4. LOCAL 환경인 경우 — 내 컴퓨터 앱은 "내 컴퓨터에서 로그인"으로 한 번 로그인해 주는 방식이에요. 로그인용 브라우저 창이 안 열리면 화면 안내에 따라 Specnote 도우미를 켜 주세요.

결과가 이상해요 — 됐다 안 됐다 해요

증상: 같은 테스트가 어떤 날은 통과, 어떤 날은 실패로 오락가락해요.

1. 일시적인 걸림 — Specnote는 화면이 늦게 뜨는 정도는 스스로 다시 시도해요. 그래도 흔들린다면 대개 테스트 자체가 애매한 경우예요.
2. 널뛰기 배지 확인 — CI 탭에서 널뛰기 배지가 붙은 테스트는 "진짜 버그"보다 "테스트가 흔들리는" 경우가 많아요. 단계가 지금 화면과 맞는지 열어 보고, 애매한 단계를 다듬어 주세요.
3. 통과 조건이 어긋난 경우 — "다시 승인해 주세요" 안내가 떠 있다면, 무엇을 성공으로 볼지가 달라졌다는 신호예요. 통과 조건을 확인하고 다시 승인하면 판정이 안정됩니다.

CI 자동 검증이 안 돌아요

증상: 코드를 올려도 검증이 시작되지 않거나 CI에서 실패해요.

1. 검증 대상 주소 확인 — 가장 흔한 원인이에요. 저장소 변수 SPECNOTE_TARGET_URL에 넣은 주소가 지금 접속되는 공개 주소인지 확인해 주세요.
2. 토큰 확인 — CI 토큰을 재발급했다면 이전 토큰은 자동 폐기돼요. 저장소 비밀값 SPECNOTE_TOKEN을 새 값으로 바꿔 주세요.
3. CI 포함 스위치 확인 — CI에서 도는 건 CI 포함을 켠 테스트뿐이에요. 돌아야 할 테스트의 스위치가 켜져 있는지 확인해 주세요.

자세한 연결 구조는 CI 자동 검증 연결하기에서 다뤄요.

코드 연결(깃허브·직접 보내기)이 안 돼요

증상: 깃허브 연결이 안 되거나, 코드 보내기가 실패·지연돼요.

1. 깃허브 앱 설치 범위 — 앱을 설치할 때 검증할 저장소가 대상에 포함됐는지 확인하세요. 저장소를 새로 만들었다면 깃허브의 앱 설정에서 접근 권한을 넓혀 주면 됩니다.
2. 첫 전송은 원래 느려요 — 100개 파일 기준 3060초 정도예요. 두 번째부터는 바뀐 부분만 보내 510초면 끝납니다.

그래도 안 풀린다면

• 화면 오른쪽 아래 채팅으로 물어보세요. 상황을 적어 주시면 함께 봐 드려요.
• 이메일 — support@specnote.io 로 증상과 함께 보내 주세요. 실패한 검증이 있다면 그 결과 화면(또는 오류 코드)을 같이 알려 주시면 훨씬 빨라요.

기본 개념부터 다시 정리하고 싶다면 핵심 용어 한눈에와 자주 묻는 질문도 함께 봐 주세요.