[사내AX] n8n 유저가 Claude Code를 만났을 때 — 버리지 않고 합치는 법

📝 한줄 요약

n8n 워크플로우를 Claude Code로 관리하고 싶어서, 3번의 시행착오 끝에 "소스코드 참조 + MCP API + 팀 컨벤션"을 합친 통합 스킬을 만들었습니다.

🎯 이런 분들께 도움돼요

• n8n을 쓰고 있는데, Claude Code가 나오면서 "이걸로 갈아타야 하나?" 고민 중인 분

• Claude Code로 n8n 워크플로우 자동 생성/수정/실행 프로세스를 만들어보고 싶은데 어디서부터 시작할지 모르겠는 분

😫 문제 상황 (Before)

저는 n8n으로 AI스터디 운영 자동화(문자 발송, 일정 안내 등)를 하고 있었습니다. Claude Code가 나오면서 "이걸로 다 넘어갈까?" 하는 생각이 들었습니다.

그런데 n8n을 버리자니, 이미 갖춰진 게 너무 많았습니다:

• 스케줄러 노드, 웹훅 트리거 등 잘 만들어진 노드들

• Airtable, Slack, Gmail 등 이미 연동된 서비스들

• 한 번만 연결해두면 되는 credential 관리

• 비개발자도 시각적으로 흐름을 볼 수 있는 UI

이걸 다 버리고 Claude Code로 "나만의 n8n"을 처음부터 새로 만드는 건 비효율적이었습니다.

하지만 n8n도 문제가 있습니다. 비개발자가 쓰기에는 진짜 어렵습니다. 노드 파라미터, JSON 구조, 표현식 문법... 하나하나 배워야 할 게 많습니다.

"비개발자가 어떻게 하면 쉽게 운영 자동화를 할 수 있을까?"

이 질문에서 출발해서, n8n을 버리는 대신 Claude Code가 n8n을 잘 다룰 수 있게 만드는 방향으로 가닥을 잡았습니다. 어떻게 개선해야 할지 방향을 모른 채, 이것저것 시도해가며 배워갔습니다.

🛠️ 사용한 도구

• Claude Code: 스킬 설계, 코드 분석, 프로젝트 구현 전반

• 모델: Claude Opus 4.5

• n8n: n8n Cloud (워크플로우 자동화 플랫폼)

• n8n-mcp: n8n 워크플로우를 API로 관리하는 MCP 서버

용어 안내

• 스킬(Skill): Claude Code에게 미리 알려주는 지침 문서. "이 팀에서는 이렇게 작업한다"를 적어두면 매번 설명 안 해도 됩니다.

• MCP: 외부 도구와 Claude Code를 연결하는 프로토콜. n8n-mcp를 연결하면 Claude가 직접 워크플로우를 생성/수정/삭제할 수 있습니다.

• 서브모듈: 다른 프로젝트의 코드를 내 프로젝트 안에 포함시키는 방법. 여기서는 n8n 공식 소스코드를 프로젝트에 넣어서 Claude가 직접 읽게 했습니다.

🔧 v1. 남이 만든 스킬을 설치해봤다 — "되긴 되는데..."

접근법: MCP 서버가 모든 걸 처리. 노드 정보 조회도 MCP, 워크플로우 생성/수정/삭제도 MCP. 스킬 7개는 "MCP를 어떻게 호출하는지" 가이드하는 역할.

처음에는 직접 만들 생각이 없었습니다. GitHub에 누군가 만들어둔 n8n 전용 도구들이 있었고, 설치하면 바로 쓸 수 있었으니까요.

• n8n-mcp — n8n 노드 정보 조회 + 워크플로우 관리 MCP 서버

• n8n-skills — Claude Code용 n8n 스킬 7개 패키지

📦 설치한 것들

이 두 가지를 설치하고 MCP 서버를 연결했습니다. 스킬 7개는 이런 것들이었습니다:

• n8n-mcp-tools-expert — MCP 도구 사용 가이드 (진입점)

• n8n-expression-syntax — 표현식 문법 패턴

• n8n-workflow-patterns — 워크플로우 아키텍처 패턴

• n8n-node-configuration — 노드 설정 가이드

• n8n-validation-expert — 검증 오류 해석

• n8n-code-javascript — Code 노드 JavaScript 가이드

• n8n-code-python — Code 노드 Python 가이드

⚠️ 쓰면서 느낀 비효율

• 참고 문서에 가까운 것까지 전부 독립 스킬 → 7개 중 어떤 걸 써야 하는지 매번 판단 필요

• "1개 스킬 + 참조 문서로 합치면 되지 않을까?" 생각도 했음 — 아래처럼 진입점 하나에 참조 문서를 필요할 때만 불러오는 구조

  사본

  .claude/skills/n8n/
    SKILL.md              ← 진입점 (자동 로드)
    references/
      expression-syntax.md  ← 필요할 때만 로드
      workflow-patterns.md
      node-configuration.md
      ...

  하지만 스킬 구조를 바꿔도 근본 문제가 남음

• 근본 문제: 노드 정보를 매번 MCP에 물어보는 방식 → Slack 노드 필수 필드를 어제도 물어보고 오늘도 물어봄

🚫 팀 맥락 부재

• 우리 팀의 credential ID를 모르니 매번 알려줘야 함

• 네이밍 규칙, 자주 쓰는 패턴 같은 컨벤션이 전혀 없음

"매번 같은 걸 물어보는 AI"가 답답해지기 시작했습니다.

🔧 v2. "직접 만들어야겠다" — 유튜브에서 힌트를 얻다

접근법: MCP 없이, n8n 소스코드를 프로젝트에 넣어서 Claude가 노드 구조를 직접 읽게 함. 워크플로우 생성/수정은 curl로 n8n API를 직접 호출. 팀 컨벤션과 삽질 기록을 스킬 문서에 사전 기록.

💡 아이디어의 시작

어떻게 개선할지 찾아보던 중, 한 유튜브 영상에서 n8n 공식 GitHub 레포 안에서 직접 Claude Code를 실행해서 워크플로우를 만드는 걸 봤습니다.

"아, n8n 소스코드를 직접 보게 하면 노드 구조를 정확히 알 수 있겠구나!"

이 아이디어에서 출발해 직접 스킬을 만들기 시작했습니다. n8n 소스코드를 프로젝트에 서브모듈로 넣고, Claude가 노드의 .ts 파일을 직접 읽어서 파라미터를 파악하게 했습니다.

📝 팀 컨벤션 구축

여기서 멈추지 않고, 실제로 워크플로우를 만들면서 겪은 시행착오를 하나씩 기록해갔습니다:

우리 팀 워크플로우의 네이밍 규칙을 분석해서 정리해줘

credential을 어떻게 참조해? 기존 워크플로우에서 뽑아올 수 있어?

실수 없이 한방에 만들려면 어떤 지침이 더 필요해?

이렇게 하나씩 물어보고 답을 정리하면서, 네이밍 규칙, credential 목록, 자주 쓰는 워크플로우 패턴, 스티키노트 규칙 등을 스킬 문서에 추가했습니다.

🐛 삽질 6건 — Claude가 "성공"이라 했지만

그리고 실제로 워크플로우를 만들어 테스트했더니... 에러가 6개 연속 터졌습니다.

Webhook의 body 구조가 달라서 Switch 노드가 데이터를 못 읽는 문제, Merge 노드 입력 개수를 안 맞춰서 생긴 문제, Switch 후 Merge 패턴 자체가 잘못된 문제 등. Claude가 만들어놓고 "성공"이라고 했는데 실제로는 안 돌아간 겁니다.

이 삽질들을 모두 "삽질 기록"으로 스킬에 추가했습니다. 같은 실수를 두 번 하지 않기 위해서요.

🔀 스킬 구조 개편

처음에는 하나의 스킬로 만들었는데, 계획/구현/검증이 뒤섞이니까 실수가 반복됐습니다. 그래서 역할별로 3개 스킬(계획/구현/검증)로 분리했고, 총 약 1,228줄이 됐습니다. v1과 달라진 점은, 참고 문서(네이밍 규칙, credential 목록, 워크플로우 패턴 등)를 스킬이 아닌 별도 참조 폴더에 분리한 것입니다. 스킬은 "이렇게 만들어라, 이렇게 검증해라"라는 행동 지침만 담고, 세부 정보는 스킬이 필요할 때 참조 문서를 불러오는 구조로 바꿨습니다.

🚧 v2의 한계

v1보다 훨씬 나았지만, 또 다른 한계가 보이기 시작했습니다:

• 3개 스킬을 매번 전환하는 게 번거로움

• 워크플로우 생성/수정을 curl로 직접 호출해야 함 — 매번 URL, 인증 헤더, JSON 본문을 수동으로 구성해야 하고, 복잡한 워크플로우 JSON을 bash 문자열로 만들다 보면 따옴표 하나 빠져서 에러가 나기 일쑤

• MCP가 제공하는 자동 검증 기능을 못 씀 — 워크플로우를 만든 뒤 "이거 맞게 만들어졌어?"를 확인하려면 직접 실행해보고, 실행 로그를 또 curl로 조회해서 수동으로 판단해야 했음. MCP라면 validate_workflow 한 번이면 끝

같은 작업을 curl과 MCP로 할 때 차이를 비교하면 이렇습니다:

"잠깐, v1의 MCP 방식도 장점이 있었는데?"

🔧 v3. "버리지 말고 합치자" — Claude가 알아서 방향을 잡아줬다

접근법: v1과 v2의 장점만 합침. 노드 정보는 소스코드에서 직접 읽고(v2의 장점), 워크플로우 생성/검증은 MCP로 처리하고(v1의 장점), 팀 컨벤션과 삽질 기록은 스킬 문서에 사전 기록(v2의 장점).

🤖 Claude에게 비교를 맡기다

v1(MCP 기반)과 v2(소스코드 기반)를 둘 다 써보니, 각각 장단점이 명확했습니다. 그런데 이걸 어떻게 합쳐야 할지 감이 안 왔습니다.

그래서 Claude에게 두 프로젝트를 동시에 보여줬습니다:

이 프로젝트(v1)랑 저 프로젝트(v2) 비교해봐. 어떤 방식이 더 효율적이야?

Claude가 돌아온 답이 인상적이었습니다. 6개 관점(노드 정보, 정보 접근, Credentials, typeVersion, 워크플로우 생성, 검증)에서 장단점을 테이블로 정리하더니, "이상적인 조합은 두 방식의 장점을 합치는 것"이라고 결론을 냈습니다.

✅ 역할 분담 확정

그 결론이 바로:

🤔 "왜 다시 MCP를?"

여기서 "v1도 MCP 썼는데 비효율적이었잖아, 왜 v3에서 다시 MCP를 써?"라고 생각할 수 있습니다. 핵심 차이는 MCP를 어디에 쓰느냐입니다. v1은 MCP로 노드 정보 조회까지 했습니다. "Slack 노드 필수 필드가 뭐야?"를 매번 MCP에 물어보니까 토큰이 낭비된 거죠. v3는 노드 정보는 소스코드에서 직접 읽고, MCP는 워크플로우를 실제로 만들고 검증하는 것에만 씁니다. 잘하는 것만 시키는 겁니다.

⚡ 하루 만에 구현

이 역할 분담을 확정한 뒤, OhMyOpenCode의 플래닝 에이전트(Metis)가 "이 구조를 만들려면 뭘 해야 하는지" 8개 핵심 질문을 스스로 도출하고 답을 내서 실행 계획을 짰습니다. 그 계획에 따라 하루 만에 구현했습니다:

1. 프로젝트 초기화

2. n8n 소스코드를 서브모듈로 추가 (v2.5.0 안정 태그 고정)

3. MCP 서버 연결 및 환경변수 설정

4. 팀 컨벤션 참조 문서 6개 복사 (네이밍, credential, 패턴 등)

5. 통합 스킬 작성 — 핵심. "소스코드 볼지 MCP 쓸지" 결정 트리 포함

6. 프로젝트 가이드 작성

7. README 작성

8. E2E 스모크 테스트 — 서브모듈 읽기 → 워크플로우 생성 → 검증 → 삭제 성공

✅ 결과 (After)

Before vs After

결과물

아직 실전에 본격 투입하기 전이라 "주 N시간 절약"처럼 정량적인 효과를 말하긴 어렵습니다. 하지만 구조적으로 확실히 나아졌다고 느낍니다:

• 진입점이 1개라서 "어떤 스킬 쓰지?" 고민이 사라짐

• 결정 트리가 있어서 상황에 따라 소스코드/MCP를 자동으로 선택

• 팀 맥락이 사전 기록되어 있어서 매번 설명할 필요 없음

• 삽질 기록이 있어서 같은 실수 반복 가능성 감소

📂 v3 최종 프로젝트 구조

최종적으로 프로젝트는 이렇게 생겼습니다:

geniefy-n8n-skills/
├── .claude/skills/        ← 통합 스킬 (333줄, 진입점)
├── references/            ← 팀 컨벤션 참조 문서 6개
│   ├── naming-rules.md       네이밍 규칙
│   ├── credentials.md        credential 목록
│   ├── workflow-patterns.md  자주 쓰는 패턴
│   ├── troubleshooting.md    삽질 기록 6건
│   └── ...
├── n8n/ (서브모듈)         ← n8n 공식 소스코드 (v2.5.0)
└── MCP 서버 연결           ← 워크플로우 생성/검증 담당

🔄 실제로 이렇게 동작합니다

"Slack으로 알림 보내는 워크플로우 만들어줘"라고 요청하면:

① 스킬 읽기: 결정 트리 확인 → 노드 정보는 소스코드, 생성은 MCP
    ↓
② 소스코드 참조: n8n/packages/nodes-base/Slack → 필수 파라미터 파악
    ↓
③ 참조 문서 확인: credential ID, 네이밍 규칙, 삽질 기록
    ↓
④ MCP로 생성: 워크플로우 자동 생성 + 검증

스킬이 "무엇을 어디서 가져올지" 판단하고, 소스코드에서 정확한 정보를 읽고, 참조 문서로 팀 규칙을 적용한 뒤, MCP로 실제 워크플로우를 만듭니다. 이 전체가 하나의 요청으로 돌아갑니다.

💬 이 과정에서 배운 AI 활용 팁

효과적이었던 것

1. AI에게 매번 같은 걸 설명하지 말고, 스킬 문서로 사전에 맥락을 줘라

   • credential ID, 네이밍 규칙, 자주 쓰는 패턴 등을 한 번 정리해두면 매번 설명 안 해도 됩니다

   • "이 팀에서는 노드 이름을 이렇게 짓는다"를 스킬에 적어두면, Claude가 알아서 따릅니다

2. 두 가지 방식을 비교할 때, AI에게 동시에 보여주고 판단을 맡겨라

   • "A 방식 분석해줘", "B 방식 분석해줘"를 따로 하지 말고, 둘 다 보여주고 "비교해봐"라고 하니까 장단점 테이블을 만들고 합치는 방향까지 제안해줬습니다

3. 실패를 문서화하라

   • 에러 6건을 "삽질 기록"으로 스킬에 추가했더니, 같은 패턴의 실수가 반복되지 않았습니다

   • AI는 과거 대화를 기억하지 못하지만, 문서에 적어두면 매 세션마다 읽습니다

🌍 다른 업무에 적용한다면?

이 글에서 n8n에 적용한 방법을 정리하면, 결국 3가지 패턴입니다:

이 3가지는 n8n이 아니어도 그대로 적용됩니다. 예시를 보면:

Airtable 자동화

Slack 봇 개발

핵심은 "AI가 매번 새로 알아내야 하는 정보를 줄이는 것"입니다.

• ① 참조 자료로 도구 구조를 알려주고,

• ② 실행 도구로 실제 작업을 맡기고,

• ③ 사전 맥락으로 팀 규칙을 기록해두면

• — 어떤 도구든 같은 패턴으로 AI를 활용할 수 있습니다.

🚀 앞으로의 계획

1. 실전 투입: 이 스킬로 실제 n8n 워크플로우를 만들어보면서, 부족한 부분을 발견하고 삽질 기록을 계속 추가할 예정입니다

2. 팀 공유: 검증이 끝나면 팀원들도 이 스킬을 쓸 수 있게 공유해서, 팀 전체의 n8n 워크플로우 품질을 높이는 것이 목표입니다