디지털 아키텍처를 설계하다 보면, 설계도보다 먼저 쌓이는 게 있습니다. 바로 삽질 로그입니다.

저는 지난 1년 동안 Cursor, Antigravity, MCP 서버, Google Cloud, 특허·상표 도구들을 엮으면서 수많은 실패를 겪었습니다. 그때마다 "왜 안 되지?"를 외치고, 며칠 뒤에야 원인을 찾곤 했죠. 그런데 돌아보니, 그 실패들이 결국 AGENTS.md 규칙, .cursor 구조, MCP 서버 설계 원칙으로 굳어지면서 지금의 Work 아키텍처를 만들었습니다.

오늘은 그중에서도, 제 디지털 아키텍처를 결정적으로 바꿔 놓은 7가지 실패 사례를 골라 정리해 보려 합니다. 단순한 하소연이 아니라, 각각이 어떤 설계 결정을 낳았는지까지 함께 적어 두겠습니다.

1. mcp_config.json이 어디 있는지도 몰랐던 시절

첫 번째 실패는 아주 단순했습니다. "MCP 서버를 어디에 등록해야 하는지"를 몰랐던 겁니다.

Antigravity IDE에서 Gmail·캘린더·구글 드라이브 MCP를 붙이려다가, 저는 한참 동안 설정 파일을 찾지 못했습니다. 공식 문서를 대충 본 기억은 있는데, 막상 IDE 안에서 어디를 클릭해야 mcp_config.json이 열리는지 감이 안 왔습니다.

결국 시행착오 끝에 알게 된 경로는 이것이었죠.

  • 에이전트 창 우측 상단 ⋯ → MCP Servers → Manage MCP Servers → 에디터에 뜬 화면에서 View raw config → mcp_config.json 열기

이 단순한 경로를 몰라서, 저는 꽤 오랫동안 "MCP가 왜 안 붙지?"만 반복하고 있었습니다. 이 경험 이후로, 저는 모든 MCP 관련 글과 AGENTS.md에 "설정 파일 여는 경로"를 첫 번째로 적는 습관을 들였습니다.

아키텍처 교훈 ① 설계 문서는 구조보다 진입 경로부터 적어라. "어디를 눌러야 거기에 갈 수 있는가?"가 아키텍처의 첫 줄이다.

2. 7일 뒤에 끊기는 Google Calendar: 테스트 모드의 함정

두 번째 실패는 Google OAuth 토큰 7일 만료였습니다.

처음에는 모든 게 잘 돌아갔습니다. Gmail도 붙고, 캘린더도 붙고, MCP 서버는 문제 없어 보였죠. 그런데 일주일이 딱 지나자 갑자기 캘린더만 401·403 오류를 내며 작동을 멈췄습니다. 저는 MCP 서버 설정을 지웠다가 다시 만들고, 토큰도 여러 번 새로 받고, 코드도 의심했습니다. 그래도 7일이 지나면 또 끊어졌습니다.

원인은 단순했습니다. Google Cloud에서 발급한 첫 번째 OAuth 클라이언트가 "테스트 모드"였던 겁니다.

해결하려면 이렇게 해야 했습니다.

  1. OAuth 동의 화면의 배포 상태를 "프로덕션"으로 전환하고,
  2. 그 이후에 새 OAuth 2.0 클라이언트 ID를 한 번 더 발급받은 다음,
  3. Gmail·캘린더 MCP 설정을 그 새 클라이언트 ID/시크릿으로 교체해야 했습니다.

이 과정을 정확히 밟은 뒤에야, 7일마다 캘린더가 죽어버리는 악순환에서 벗어날 수 있었습니다.

아키텍처 교훈 ② 인증 계층은 "되느냐"만 볼 게 아니라 "언제까지 되느냐"까지 설계해야 한다. 테스트 모드는 데모용, 아키텍처는 프로덕션 기준으로 잡아야 한다.

3. 상대경로로 잘 붙여 놨는데, 코드 안에는 절대경로가…

세 번째 실패는 토큰 경로와 하드코딩입니다.

저는 개인 취향상, 프로젝트 안의 경로를 되도록 상대경로로 맞춰 두는 편입니다. 그래서 Calendar 토큰 파일도 ./config/token.json 같은 위치에 두고, 환경 변수로 그 경로를 넘기도록 설정했습니다.

겉보기에는 아무 문제 없어 보였는데, 일정이 도무지 조회되지 않는 겁니다. 토큰을 지웠다가 다시 발급받아도, 폴더를 옮겨도 마찬가지였습니다.

나중에 MCP 서버 코드를 직접 열어 보고 나서야 이유를 알게 됐습니다.

  • 제가 넘긴 환경 변수는 거의 무시되고,
  • 코드 안에는 절대경로가 하드코딩되어 있었던 거죠.

결국 저는 그 절대경로에 맞춰 토큰 파일을 옮기고 나서야, "아무리 토큰을 새로 받아도 안 되던" 문제가 풀렸습니다.

이 일을 겪고 난 뒤부턴, 새로운 MCP 서버를 선택할 때마다 제일 먼저 이렇게 묻습니다.

  • "이 서버는 토큰·자격 증명을 어디서 어떻게 읽나요?"
  • "경로는 환경 변수로만 제어되나요, 아니면 절대경로 하드코딩이 섞여 있나요?"

아키텍처 교훈 ③ 경로는 API처럼 다뤄라. 코드 안에 절대경로가 한 줄이라도 있으면, 그건 설계가 아니라 잠복 버그다.

4. 테스트 사용자 한 줄을 빼먹어서 생긴 인증의 늪

네 번째 실패는 테스트 사용자 누락입니다.

Google Cloud의 OAuth 동의 화면에는 "테스트 사용자" 섹션이 있습니다. 테스트 모드일 때는, 여기에 등록된 계정만 이 앱으로 로그인·동의할 수 있습니다.

저는 이걸 대충 읽고 넘어갔습니다. 그리고는 "왜 내 계정으로는 동의 화면이 안 뜨지?", "왜 접근 권한이 없다고 하지?" 라는 오류 메시지만 수차례 봤습니다.

원인은 너무 단순했습니다. 테스트 사용자 목록에 제 Gmail 주소를 추가하지 않았던 것이죠.

그 이후로는, OAuth 동의 화면을 구성할 때마다 AGENTS.md와 포스팅에서 "테스트 사용자에 본인 Gmail을 꼭 넣어라"를 체크리스트에 박아두고 있습니다.

아키텍처 교훈 ④ 보안·인증 설정에서는 "누가 들어올 수 있는가"를 옵션이 아니라 명시적인 리스트로 관리하라.

5. v1을 계속 고치느라, v2를 만들 생각조차 못 했던 Jekyll/Astro 개편기

다섯 번째 실패는 코드가 아니라 마음가짐의 문제였습니다.

현재 운영중인 다른 사이트의 초기 버전(v1)은 Babel 기반의 다크 모드 페이지였습니다. 처음에는 이것저것 조금씩 손보며 고치다 보니, 어느새 CSS와 레이아웃이 누더기가 되어 있었습니다. 그럼에도 저는 계속 v1을 붙잡고 있었습니다. "여기만 조금 더 고치면 괜찮아지겠지"라는 희망 때문에요.

결국 세 번째 시도에서야 저는 결심했습니다. "이식이 아니라 재창조다."

  • v1에서는 텍스트 콘텐츠만 가져오고,
  • 뼈대와 디자인은 Astro v2 환경에 맞게 완전히 새로 설계했습니다.
  • Cursor로 전체 구조를 잡고, 제미나이 CLI로 하위 페이지들을 밀어 올리는 식으로 도구 역할도 분리했죠.

그 결과가 라이트 모드 Astro v2입니다. 이 경험은 저에게 "기존 구조를 고치는 것과, 새 구조를 설계하는 것은 다른 문제"라는 걸 몸으로 가르쳐 주었습니다.

아키텍처 교훈 ⑤ 누더기가 된 v1을 덧대는 데 쓰는 에너지는, 종종 v2 전체를 설계할 수 있는 에너지다. 일정 임계점을 넘으면 리팩토링이 아니라 리플레이스(Replace)를 진지하게 검토해야 한다.

6. 워크스페이스 루트가 달라질 때마다 사라지는 .cursor

여섯 번째 실패는 Cursor의 .cursor 적용 범위였습니다.

저는 Work 루트(C:\\Work)에 .cursor를 두고, Rules/Skills/Commands/Agents를 잘 구성해 놨습니다. 그런데 어느 날, 개별 프로젝트 폴더만 열어서 작업을 하다 보니, 분명히 만들어 둔 스킬과 룰이 전혀 적용되지 않는 겁니다.

나중에 알고 보니 Cursor는 "어느 폴더를 워크스페이스 루트로 열었는지"에 따라 .cursor를 다르게 읽습니다.

  • C:\\Work를 열면 루트 .cursor가 적용되지만,
  • C:\\Work\\nan-IP.me-Blog만 열면, 그 안에 있는 .cursor만 찾는 식이었죠.

이 실패 이후로는, README와 AGENTS.md에 다음 문장을 항상 넣습니다.

  • "Work 전체를 대상으로 규칙·스킬을 쓰고 싶다면, 반드시 C:\\Work 또는 Work.code-workspace를 열 것."

아키텍처 교훈 ⑥ 설정은 파일보다 루트 컨텍스트에 묶인다. "어디에 두었는가" 못지않게 "어디서 열었는가"를 설계에 포함해야 한다.

7. 실패는 로그가 아니라 스펙이다

마지막 일곱 번째는, 개별 사건이 아니라 태도에 대한 변화입니다.

예전에는 문제가 생기면, 그때그때 해결하고 잊어버렸습니다. 토큰 만료였든, 절대경로 버그였든, 테스트 사용자 누락이든, "다시는 이런 일 없겠지"라고 생각하고 그냥 넘어갔죠.

하지만 MCP, AI IDE, 여러 IP 프로젝트를 함께 운영하다 보니, 한 번 겪은 실패가 다른 레이어에서 반복되는 걸 여러 번 보게 됐습니다. 그때부터는 방향을 바꿨습니다.

  • 삽질이 한 번 발생하면,
    • AGENTS.md에 규칙으로 남기고,
    • .cursor/rules/에 룰로 남기고,
    • 필요하면 블로그 포스팅(arch)으로까지 끌어올립니다.

그래서 지금의 디지털 아키텍처는 멋진 다이어그램이 아니라, 이런 문장들 위에 서 있습니다.

  • “Google OAuth는 테스트 모드 7일 한도를 인지하고, 프로덕션+새 클라이언트 ID를 전제로 설계한다.”
  • “MCP 서버를 선택할 때는 토큰 경로·환경 변수를 먼저 확인하고, 절대경로 하드코딩 여부를 검증한다.”
  • “루트 워크스페이스를 기준으로 .cursor를 설계하고, 프로젝트 단위로 열 때의 동작을 문서로 명시한다.”

아키텍처 교훈 ⑦ 실패는 로그로 남기면 기록이고, 규칙으로 승격시키면 아키텍처가 된다.

이 글을 읽는 분들도, 요즘 AI 도구와 MCP, 클라우드를 엮다 보면 저와 비슷한 함정에 빠질 수 있을 겁니다. 중요한 건 실패를 얼마나 적게 하느냐가 아니라, 한 번 겪은 실패를 얼마나 빠르게 설계의 일부로 편입시키느냐라고 생각합니다.

앞으로도 저는 계속 삽질을 할 겁니다. 다만 이제는, 그 삽질이 디지털 아키텍처를 단단하게 만드는 재료가 되도록 기록하고 구조화해 볼 생각입니다.