[Claude code] Paseo 사용 전에 설명서부터 만들어보기: Paseo 한국어 가이드 사이트를 하루에 완성한 후기

📝 한줄 요약

써 보려던 도구 Paseo의 비공식 한국어 초보자 가이드를 Claude Code로 하루 만에 만들어보았습니다. 슬라이드 87장짜리 웹페이지이고, 만드는 동안 "이 도구를 왜 쓰는가"라는 제 질문에도 답을 얻었어요.

ALT

한국어로 된 웹사이트의 홈페이지

바쁘시면 이것만 읽으셔도 돼요.

• Claude Code로 만들었고, 첫 요청부터 마지막 배포(인터넷에 올리기)까지 6시간 55분 걸렸어요

• 에이전트(일을 나눠 맡는 AI) 75개가 함께 일했고, 사실 검증에서 첫 원고 60곳을 고쳤어요

• AI가 연습 프로젝트로 Paseo를 실제로 돌리고, 그 화면을 직접 찍어 가이드에 넣었어요

• "Paseo가 Orca보다 낫다는 근거는 못 찾았다"처럼 모르는 것을 모른다고 답해 준 점이 인상적이었어요

• 쪽 번호 디자인은 시안 3개를 먼저 보고 골랐어요

• 아쉬운 점도 있어요. 요청을 하나씩 더하다 보니 시간과 사용량이 많이 들었어요

🎯 이런 분들께 도움돼요

• 새 AI 도구를 제대로 쓰기 전에 "이게 뭔지"부터 정리하고 싶은 비개발자, AI 초급자

• 그중에서도 이런 분들께 더 맞을 것 같아요

  • Claude Code와 Codex에 원격 모드(밖에서 폰으로 일을 시키는 기능)가 있는데 Paseo, Orca, Hermes 같은 도구를 왜 쓰는지 궁금한 분

  • AI가 쓴 글의 사실 확인을 어떻게 맡길지 고민하는 분

  • Paseo를 처음 써 보려는 분

😫 문제 상황 (Before)

같은 스터디 기수의 '도시아재'님께서 Orca를 설치해 적용해 보시기 전에, 공부하는 차원에서 매뉴얼을 만들어 보셨다는 글을 읽고 감동과 감화를 받았어요. 바로 이 글이에요.

Orca, 왼쪽에 파일 목록이 없어서 당황하셨나요? — 초보가 정리한 적응 노트

지녕 스터디장 님은 Paseo를 Orca보다 더 많이 사용 중이시라고 하셨어요. 그래서 기왕 설치하고 사용해 보는 거, 저도 도시아재님처럼 Paseo 매뉴얼을 만들면서 공부도 하고 설치도 하고 사용해 보기로 했어요. Paseo는 내 컴퓨터에 깔아 둔 Claude Code나 Codex 같은 AI 일꾼을 한 화면과 폰에서 부리는 앱이에요. Orca도 AI 일꾼 여럿을 한 화면에서 부리는 비슷한 종류의 앱입니다.

이유가 하나 더 있었는데, 제가 먼저 이해하고 싶었어요. Claude Code와 Codex에도 원격 모드가 있는데 굳이 Paseo, Orca, Hermes(켜 둔 컴퓨터에 깔아 두고 텔레그램 같은 메신저로 일을 시키는 AI 에이전트)를 왜 쓰는지, 깔아만 두고 제대로 써 보기 전에 스스로 정리해 두고 싶었거든요.

🛠️ 사용한 도구

• 도구명: Claude Code 데스크톱 앱(에이전트 여러 개에 일을 나눠 주는 워크플로 기능 사용), Vercel(웹페이지를 인터넷에 올려 주는 서비스)

• 모델: Claude Opus 5.5(메인 대화와 워크플로 에이전트), Claude Sonnet 5.5(따로 부른 검증·조사 에이전트 5개)

• 특이사항: 디자인은 제가 만들어 갖고 있던 'stardust.md' 디자인을 참고해 달라고 했어요. 내용은 Claude Code가 Paseo 공식 문서 60쪽과 공개된 프로그램 원본(소스)을 읽고 썼습니다

🔧 작업 과정

조사하는 AI, 쓰는 AI, 틀린 곳을 잡는 AI가 따로 있었어요

오전 10시 35분, 참고할 Orca 가이드와 원하는 디자인을 알려 주고 이렇게 부탁했어요.

자료조사를 잘 해주고, 비개발자나 AI의 초급자도 따라서 설치하고 사용해볼 수 있게 편한 용어와 은유로 친절하게 설명해줘.

Claude Code는 혼자 다 쓰지 않았어요. 조사 에이전트 8개가 영역을 나눠 자료를 정리하고, 비평 에이전트 1개가 빠진 곳과 어긋난 곳을 짚었어요. 이어서 집필 에이전트 8개가 장을 하나씩 맡아 동시에 썼는데, 쓰기 시작한 지 29분 만에 71장짜리 첫 원고가 나왔어요. 첫 요청부터 따지면 한 시간이 채 안 걸렸습니다.

검증은 제가 시키지 않았는데 Claude Code가 알아서 검증 단계를 넣더라고요. 에이전트 20개가 42분 동안 사실 검증, 문장 다듬기, 코드 점검을 나눠 했고, 사실 검증에서만 60곳을 바로잡았어요. "코드와 대화는 Paseo 쪽으로 전송되지 않습니다"라는 문장은 대화까지 안 나간다는 근거가 없다며 "코드는 내 컴퓨터에 그대로 있습니다"로 바뀌었어요.

그 뒤 검증에서도 틀린 곳이 더 나왔어요. 같은 상황인데 한 장은 '데몬 재시작' 버튼을, 다른 장은 'Stop daemon' 버튼을 누르라고 적혀 있었어요(데몬은 뒤에서 계속 돌아가는 관리 프로그램이에요). 비교표에 Claude Code만 되는 것처럼 적힌 기능이 Codex에도 있다는 지적이 나와서 "둘 다 된다"로 고쳐졌고요. 쓴 쪽이 아닌 다른 AI가 봐야 보이는 게 있더라고요.

연습용 '별빛 카페'를 만들어 실제 화면을 찍어 왔어요

ALT

한국어 웹사이트의 스크린샷

첫 원고에는 화면을 본떠 그린 약도 그림만 있었어요. 따라 하는 분들께는 실제 화면이 낫겠다 싶었어요.

그리고 가져올 수 있다면, 첨부파일처럼, 실제의 파세오 화면 캡쳐가 적절히 들어가고 배치되면 설치하며 따라가는 사람들 입장에서 더 쉬울 듯해.

Claude Code는 바로 찍지 않고, 어디까지 찍을지 선택지 세 개를 주며 물었어요. 저는 "데모 프로젝트까지"를 골랐어요. 그러자 Claude Code가 '별빛 카페'라는 작은 카페 소개 페이지를 연습용으로 만들고, Paseo에서 AI 일꾼에게 영업시간 바꾸기와 인사말 넣기를 실제로 시켰어요.

그렇게 찍은 화면이 38장이에요. 컴퓨터 이름은 가렸고, QR과 페어링 링크(폰을 연결하는 비밀 주소) 화면은 아예 찍지 않았어요. 중간에 데스크톱 앱을 직접 조작하는 방법이 막혔는데, Claude Code가 Paseo 공식 웹 화면 쪽으로 방법을 바꿔서 마저 찍었어요.

제 가설에는 "절반만 맞다"는 답이 왔어요

ALT

한국어 단어가 적힌 페이지

만드는 동안, 정작 제가 궁금했던 걸 물었어요(오케스트레이션은 AI 여럿에게 역할을 나눠 맡기는 걸 말해요).

요즘 클로드코드나 코덱스도 원격모드가 가능한데, 굳이 파세오나 오르카를 쓰는 이유는, 오케스트레이션을 통해 작업에 해당하는 각 역할에 맞는 모델을 지정하고 사용할 수 있기 때문인가?

조사 결과는 "절반만 맞다"였어요. 원격으로 시키기와 역할마다 모델 정하기는 Claude Code와 Codex만으로도 이미 됩니다. 원격만 원한다면 Paseo는 없어도 돼요. Paseo와 Orca가 보태 주는 건, 만든 회사가 서로 다른 AI(Claude, Codex, Gemini 등)를 한 화면과 폰 앱 하나에서 섞어 쓰게 해 주는 점이었어요.

다른 질문에도 답이 솔직했어요.

• 첫 요청에 제가 "요즘 오르카보다 파세오가 낫다고 하는 사람들도 많고"라고 썼는데, 그런 근거는 찾지 못했다고 했어요. 평가가 엇갈렸고, 개발자들이 프로그램을 올려 두는 GitHub의 별('좋아요' 같은 것) 수는 집계 사이트(openalternative.co) 기준으로 Orca가 4배 이상 많았대요. 그래서 가이드에는 "쓰임새가 다르다"고 적혀 있어요

• 오케스트레이션이 토큰(AI 사용량 단위)을 아껴 주느냐고 물으니 대체로 아니라고 했어요. 일꾼이 늘면 토큰도 그만큼 더 든다고요

• Hermes로 Paseo에 일을 시킬 수 있느냐는 질문에는 원리로는 되지만 공식 문서에 없고 직접 해 보지도 않았다고 답했어요. 문서에 있는 건 반대로 Paseo가 Hermes를 부르는 방법이었어요

• Windows 전환 스위치도 넣었는데, 실제 Windows PC에서는 확인하지 못했다는 점을 가이드에 그대로 적어 두었더라고요

모르는 것을 모른다고 적어 준 이 답들이 인상적이었어요.

쪽 번호는 시안 3개를 보고 골랐어요

ALT

한국어로 된 웹사이트의 홈페이지

배포한 뒤에 디자인 욕심이 하나 생겼어요.

그리고 각 페이지의 배경에, 기존의 디자인을 헤치지 않게, 은은하고 투명하게 큰 숫자로 페이지 번호를 넣어줄 수 있을까? 이는 먼저 예시 디자인을 먼저 검토맡고 진행해줘.

Claude Code는 시안 A, B, C를 그림으로 만들어 보여 주고, 시안마다 장단점을 적어 줬어요. 저는 C를 골랐고, 표지에도 넣을지, 폰에서도 보이게 할지까지 모두 세 번 고르고 나니 77장에 쪽 번호가 들어갔어요.

가이드에 '만든 곳' 표시로 넣은 MaumFlex 로고는 한 번 바뀌었어요. 처음엔 Claude Code가 로고 파일을 찾지 못해 글자로 만든 임시 마크를 넣어 두었고, 제가 공식 로고 파일을 주자 그걸로 바꿔 줬어요.

하나씩 더하다 보니 하루가 갔어요

Windows 전환, 실제 화면, 폰용 내려받기 링크, 로고, Hermes 비교, 쪽 번호를 저는 한 번에 말하지 않고 생각날 때마다 그때그때 더했어요. 그때마다 고치고 검증하는 일이 되풀이됐고, 배포만 5번 했어요. 처음부터 다 말했으면 더 빨랐을 거예요.

✅ 결과 (After)

Before vs After

결과물

Paseo 산책 가이드: https://paseo-guide.vercel.app

ALT

한국사이트 스크린샷

• 컴퓨터에서는 16:9 슬라이드로 한 장씩, 폰에서는 세로로 이어 읽을 수 있어요

• Mac·Windows 스위치를 누르면 설치 방법과 단축키가 그 컴퓨터 기준으로 바뀌어요

• 폰으로 열면 iPhone은 App Store, 안드로이드는 Google Play 버튼이 보여요

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

효과적이었던 것

1. 참고 사례와 독자를 먼저 알려 주기: 참고할 가이드 주소를 주고 "비개발자나 AI의 초급자도"라고 적었더니 첫 원고부터 쉬운 말과 비유로 써 줬어요

2. 쓴 AI와 검사하는 AI 나누기: 다른 에이전트가 원자료와 대조하니 첫 원고에서 고칠 곳이 60곳 나왔어요

3. 내 짐작을 그대로 적어서 묻기: "~때문인가?"라고 물으니 어디가 맞고 어디가 틀린지 짚어 줬어요

4. 시안부터 받기: 쪽 번호는 적용하기 전에 골랐더니 적용한 뒤에 디자인을 뒤집는 일이 없었어요

이렇게 하면 안 돼요

1. 요청을 하나씩 더하기: 저는 여섯 가지를 그때그때 더했고, 그때마다 고치고 검증하는 일이 되풀이됐어요. 처음부터 다 말했으면 더 빨랐을 거예요

2. 에이전트 수십 개를 가볍게 보기: 첫 요청부터 마지막 배포까지 7시간 가까이 걸렸고 사용량이 컸어요. 기록에 남은 워크플로 7회분만 따져도 토큰이 약 1,948만 개였습니다(따로 부른 에이전트 6개의 약 154만 개와 메인 대화의 사용량은 여기에 들어 있지 않아요)

3. AI가 쓴 글을 검증 없이 올리기: 그럴듯한 문장에도 틀린 곳이 있었어요

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

"설명서부터 만들기"는 다른 도구에도 써 볼 수 있을 것 같아요. 새로 쓸 프로그램의 공식 문서를 AI에게 읽히고 초보자용 안내서를 만들게 한 다음, 그걸로 공부하는 거예요. 업무 매뉴얼이나 안내 자료를 만들 때도 여러 AI에게 일을 나눠 맡기고 검증은 따로 시키는 방식을 써 볼 수 있겠다 싶어요.

🚀 앞으로의 계획

이제 이 가이드를 따라 Paseo를 실제로 써 보려고 해요. 써 보다가 가이드와 다른 점이 보이면 고쳐 볼 수 있고, 실제 폰과 Windows PC에서 확인해 볼 수도 있을 것 같아요.

📋 재사용 가능한 프롬프트

대괄호 [ ] 안은 본인 상황에 맞게 바꿔 쓰세요.

프롬프트 1: 공식 문서로 초보자 가이드 만들기

[도구 이름]의 공식 문서([문서 주소])를 조사해서, [비개발자나 AI 초급자]가 따라 할 수 있는 한국어 가이드 웹페이지를 만들어 줘. 쉬운 말과 비유로 설명하고, 문서에서 확인한 내용만 써 줘. 확인하지 못한 것은 본문에 "확인 못 한 것"이라고 그대로 표시해 줘.

프롬프트 2: 공개하기 전에 깐깐하게 사실 확인 시키기

방금 만든 [문서나 페이지]를 공개하기 전에, 쓴 쪽과 다른 에이전트에게 검증을 맡겨 줘. 문장마다 [원자료]와 대조해서 틀렸거나 근거가 없는 곳을 찾고, 무엇을 어떻게 고쳤는지 목록으로 알려 줘. 끝까지 확인하지 못한 것도 따로 적어 줘.

프롬프트 3: 디자인은 시안부터 받기

[바꾸고 싶은 디자인 요소]를 넣고 싶어. 바로 적용하지 말고 시안을 [3]개 만들어 그림으로 보여 줘. 시안마다 장단점을 한 줄씩 적어 주고, 내가 고른 뒤에 적용해 줘.

프롬프트 4: 두 도구의 차이를 근거와 함께 묻기

[도구 A]와 [도구 B]는 뭐가 달라? 내 생각은 "[내 가설]"인데 맞는지 봐 줘. 공식 문서 같은 출처를 붙여 주고, 문서로 확인한 것과 추측인 것을 나눠서 답해 줘. 근거를 찾지 못한 것은 못 찾았다고 말해 줘.