코드를 몰라도 Claude 데스크톱 앱의 Code 탭(Claude Code) 에 말로 시켜서 나만의 비서 AI를 만드는 방법입니다. 터미널(검은 명령 창)은 거의 쓰지 않습니다.
crazy4eu(cwkim83)가 실제로 파이스(PAIS)를 만든 순서를 그대로 따라갑니다. 숫자는 2026-10-06 코드 기준입니다.
회색 상자 안의 글은 그대로 복사해서 Code 탭 입력창에 붙여 넣는 요청문입니다. 괄호 부분만 내 상황에 맞게 바꾸세요.

파이스는 어떤 물건인가

목표만 말하면 스스로 도구를 골라 실행하고, 결과를 보며 이어가는 개인 비서입니다. 메일·일정·문서 검색·코딩·자기 업그레이드까지 합니다.

실제 만든 순서 (git 기록)

처음 닷새(Phase 1~7)에 뼈대와 안전망을 다 세우고, 그 뒤 두 달은 회사 자료에 붙이는 일을 했습니다. 아래 단계도 이 순서를 따릅니다.

0단계 · 무엇을 만들지 정하고, 청사진·구조도부터 그린다

① 한 문장으로 정하기

• 예: "목표만 말하면 스스로 도구를 골라 실행하는, 내 PC에서 도는 개인 비서"
• 누가 쓰나(나 혼자 / 부서) · 무엇을 대신하나(메일·일정·문서 찾기) · 무엇은 절대 안 하나(메일 자동 발송, 파일 삭제)까지 적습니다.

② archify 설치 (구조도 그리는 스킬)

archify는 말로 설명하면 검증된 구조도(HTML, PNG로 내보내기 가능)를 그려 주는 Claude Code 스킬입니다. 위 파이스 구조도도 archify로 그렸습니다. 1단계에서 데스크톱 앱을 준비한 뒤, Code 탭 입력창에 아래처럼 붙여 넣으면 Claude가 설치해 줍니다(Node.js 18 이상 필요).

archify 스킬을 설치해 줘. 명령은 npx skills add tt-a1i/archify -g 야. Node.js 가 없으면 먼저 설치 방법을 알려 줘.

③ 청사진 요청문

나는 코드를 모른다. 내가 만들 개인 비서 AI의 청사진을 docs/blueprint.md 로 써 줘.
- 목적: (예: 목표만 말하면 스스로 도구를 골라 실행하는 내 PC용 비서)
- 사용자: (나 혼자)
- 꼭 할 일 5가지: (메일 요약, 일정 확인, 회사 문서 검색, 엑셀 정리, 매일 아침 브리핑)
- 절대 안 할 일: (메일 자동 발송, 파일 삭제, 회사 밖으로 자료 전송)
- 위험과 막는 방법: 개인정보, 비밀번호, 잘못된 삭제
- 단계별 로드맵: 한 단계는 하루 안에 끝나는 크기로
어려운 용어는 괄호로 쉽게 풀어 줘.

④ 구조도 요청문

archify 로 docs/blueprint.md 의 전체 구조도(architecture)를 그려 줘.
사용자 기기 → 웹 서버 → 도구 루프 → AI 두뇌, 그리고 도구·기억·예약 작업·안전장치(감시자)를 넣고,
한국어 라벨로, 검증(validate)까지 통과시킨 뒤 docs/구조도.html 과 PNG 로 저장해 줘. 다 되면 브라우저 패널로 보여 줘.

⑤ 단계마다 붙이는 한 줄

먼저 docs/blueprint.md 와 docs/구조도.html 을 읽고, 이번에는 (3단계)만 해. 끝나면 청사진과 구조도도 실제 코드에 맞게 고쳐 줘.

1단계 · Claude 데스크톱 앱 준비

① 설치와 로그인

1. claude.com/download 에서 Windows 설치 파일을 받아 실행합니다.
2. 시작 메뉴에서 Claude 를 열고 Anthropic 계정으로 로그인합니다.
3. 위쪽 가운데 Code 탭을 누릅니다. 업그레이드하라고 나오면 유료 플랜이 필요합니다(Claude Pro·Max·Team·Enterprise, 무료 플랜은 Code 탭 불가).

• 데스크톱 앱에는 Claude Code가 들어 있어서 따로 설치할 필요가 없습니다.
• Git for Windows(git-scm.com)를 깔아 두면 Claude가 명령을 더 잘 실행합니다(없으면 PowerShell 로 대신함).

② 작업 폴더 열기

1. 파일 탐색기에서 빈 폴더를 하나 만듭니다. 예: C:\my-agent
2. Code 탭 입력창 아래에서 환경을 Local 로 고르고 Select folder 로 그 폴더를 엽니다.
3. 전송 버튼 옆 드롭다운에서 모델을, 그 옆 선택기에서 권한 모드를 고릅니다.

③ 화면에서 알아 둘 것

• 입력창 + 버튼: 파일 첨부 · Slash commands(스킬) · Connectors(커넥터) · Plugins(플러그인)
• Terminal(Ctrl+`): 같은 폴더에서 명령을 직접 칠 수 있는 창. 이 가이드에서는 거의 쓰지 않습니다.
• Browser 패널: 만든 웹앱을 앱 안에서 바로 띄워 봅니다.
• +12 -1 같은 표시를 누르면 무엇이 바뀌었는지(diff) 파일별로 보입니다.
• 왼쪽 Customize: 커넥터·스킬·플러그인을 한곳에서 관리

④ 첫 확인 요청문

이 PC에 Node.js 와 Git 이 설치돼 있는지 확인해 줘. 없으면 무엇을 설치해야 하는지 쉬운 말로 알려 줘.
그다음 이 폴더를 git 저장소로 만들어 줘.

2단계 · AI에게 줄 '일하는 법' 파일

AI 코딩 도구는 매번 처음 보는 사람처럼 일합니다. 규칙을 CLAUDE.md 파일로 남겨 두면 매번 읽고 따릅니다. 입력창에 /init 을 치면 초안을 만들어 줍니다.

파이스의 실제 규칙에서 뽑은 것

• 숫자는 코드가 진실이다 — 문서에 "도구 41종"이라 적혀 있었는데 실제는 67종이었다. 틀린 문서는 AI에게 틀린 전제가 된다.
• 고치기 전에 관련 셀프체크를 돌리고, 커밋 직전에 전체 검사를 한 번 한다.
• 커밋 메시지는 한국어로, 왜 그랬는지와 어떻게 발견했는지를 남긴다.
• 고장을 고치면 같은 고장이 다시 나지 않게 검사를 박아 둔다.
• 큰 파일은 통째로 읽지 않는다(사용량이 빨리 닳는다).

시작용 규칙 파일 요청문

CLAUDE.md 를 만들어 줘. 내용:
- 나는 코드를 모른다. 설명은 쉬운 한국어로, 결론부터.
- 한 번에 한 단계만 하고, 끝나면 내가 직접 확인할 방법을 알려 줘.
- 기능을 만들면 그 기능을 검사하는 셀프체크도 같이 만들어.
- 비밀번호·API 키는 코드나 대화에 쓰지 말고 설정 화면이나 환경변수로.
- 단계가 끝날 때마다 git 커밋. 커밋 메시지에 왜 바꿨는지 적어.
- 문서에는 실제 코드에 있는 것만 현재형으로 쓴다.

3단계 · 뼈대: 대화 화면 + AI 두뇌 연결 (파이스 Phase 1)

Node.js 로, 외부 패키지 없이, 내 PC에서 도는 개인 비서 웹앱의 뼈대를 만들어 줘.
- server.js 가 http://localhost:8787 에 채팅 화면을 띄운다.
- AI 두뇌는 OpenAI 호환 API 로 부른다. 주소·API 키·모델은 웹의 설정 화면에서 입력하고 data/settings.json 에 저장(화면에는 가려서 표시).
- 답은 글자가 오는 대로 실시간으로 보여 준다(스트리밍).
- 접속 암호를 넣어서 암호를 모르면 아무것도 못 하게.
- 다 만들면 서버를 실행해서 브라우저 패널로 띄워 줘.

• 두뇌 고르기: Claude·OpenAI·Gemini 의 API 키, 또는 내 PC의 무료 로컬 모델(Ollama). 파이스는 여러 모델을 한 주소로 묶는 OpenAI 호환 관문을 두뇌로 써서, 모델을 바꿔 끼우기 쉽게 했습니다.
• 확인: 앱 오른쪽 Browser 패널에 채팅 화면이 뜨면 성공입니다. 내 브라우저에서 http://localhost:8787 로 열어도 됩니다.
• API 키는 Code 탭 입력창에도 붙여 넣지 않습니다. 만든 웹앱의 설정 화면에 직접 넣습니다. 붙여 넣었다면 바로 키를 새로 발급받습니다.

4단계 · 손발: 도구 루프 (에이전트의 핵심)

챗봇과 에이전트의 차이가 여기입니다. 두뇌가 "이 도구를 써야겠다"고 답하면 프로그램이 실제로 실행하고, 결과를 다시 두뇌에 보여 줍니다. 목표를 이룰 때까지 돕니다. 파이스는 최대 40바퀴, 34바퀴째에 "마무리하라"고 유도합니다.

도구 호출 루프(orchestrator.js)를 만들어 줘.
- 두뇌가 tool_calls 를 돌려주면 실행하고 결과를 다시 넣어 반복. 최대 40회, 34회째에 마무리 유도.
- 첫 도구 3개: 작업 폴더(내 문서\Agent_Workspace) 안의 파일 목록 보기 / 읽기 / 쓰기.
- 작업 폴더 밖의 경로는 무조건 거부(../ 같은 우회도).
- 화면 오른쪽에 지금 어떤 도구를 불렀는지 실시간 로그.
- 도구마다 셀프체크. 다 되면 브라우저 패널에서 "작업 폴더에 메모.txt 를 만들어 줘"로 시험해 줘.

도구 늘리기 요청문 예

도구를 하나 추가해 줘: (웹 검색 / PDF·엑셀 읽기 / 구글 캘린더 ICS 주소로 일정 읽기).
추가할 때마다 셀프체크를 만들고, 권한 표에 어느 권한으로 묶을지 같이 정해 줘.

5단계 · 안전장치: 권한 등급제 + 자율성 모드

AI에게 손발을 주면 사고도 낼 수 있습니다. 위험한 능력은 기본 OFF, 사람이 화면에서 직접 켭니다. 파이스의 실제 권한 표(코드 기준)입니다.

자율성 모드는 다른 축입니다. 🧭 계획만(읽기만 허용, 코드로 강제) / 🛡️ 신중(되돌리기 어려운 일 전에 확인, 기본) / 🚀 자동(묻지 않고 끝까지). 데스크톱 앱의 권한 모드(Plan·Manual·Auto)와 같은 생각입니다.

권한 등급제를 넣어 줘. 위험한 능력(셸 실행, 인터넷, 개인정보, 자기 코드 수정)은 기본 OFF, 화면 왼쪽에서 내가 켜고 끈다.
자율성 모드 3가지(계획만 / 신중 / 자동)도 넣고, 계획 모드는 읽기 전용 도구만 허용하도록 코드로 막아 줘.
'위험 능력은 기본 OFF' 를 셀프체크로 못박아 줘.

6단계 · 기억 · 시켜놓고 잊기 · 예약 (Phase 2~4)

기억 기능을 만들어 줘: 내가 알려 준 사실(facts)과 작업 기록(journal)을 저장하고, 대화가 끝나면 기억할 만한 것을 스스로 골라 저장. 화면에 기억 목록(보기·삭제).

'시켜놓고 잊기'를 만들어 줘: 긴 작업은 백그라운드 잡으로 돌리고, 창을 닫아도 계속 돌고, 끝나면 휴대폰으로 알림(ntfy).

예약 실행을 만들어 줘: 매일/매주/한 번. 예: 매일 아침 7시 30분에 메일·일정 요약. 컴퓨터가 꺼져서 놓친 회차는 켜진 뒤 한 번 실행.

7단계 · 자기수정과 구조대 (Phase 6~7)

파이스는 자기 코드를 고칩니다(사람 커밋 598 · 파이스 스스로 74). 대신 망가져도 살아나는 장치를 먼저 만들었습니다.

1. 고치기 전에 git 자동 백업 커밋
2. 파일 쓰기 → 문법 검사 → 평가 하네스(selftest) 통과 → 커밋. 하나라도 실패하면 원래대로
3. 재시작 → 감시자(runner.js)가 5초마다 건강 검사, 3번 연속 통과해야 '마지막 정상 버전(last-good)'으로 기록
4. 검사에 실패하면 last-good 으로 자동 되돌리기
5. 감시자·비상 화면은 '불변 층' — 에이전트가 고칠 수 없게 막아 둔다

감시자 runner.js 를 만들어 줘: server.js 를 띄우고 죽으면 다시 띄운다. 재시작 후 건강 검사가 3번 연속 통과하면 그 커밋을 data/last-good 에 기록, 실패하면 last-good 으로 되돌리고 다시 띄운다.
감시자는 src/ 를 가져다 쓰지 마(같이 죽으면 안 됨). 감시자 파일은 에이전트가 수정 못 하게 막아 줘.

selftest.js 를 만들어 줘: 모든 모듈을 실제로 불러 보고, 도구 이름 중복·위험 능력 기본 OFF·작업 폴더 탈출 거부를 검사. 실패하면 종료코드 1.
자기 코드 수정 도구는 백업 커밋 → 쓰기 → 문법 검사 → selftest → 커밋 순서로, 실패하면 되돌리게.

8단계 · 밖에서 쓰기 (폰 · 회사 밖)

• 아이폰: 사파리로 접속 → 공유 → '홈 화면에 추가' → 앱처럼 쓴다(PWA로 만들어 달라고 요청).
• 외부 주소 만들기(Cloudflare 터널) — Code 탭에 이렇게 요청합니다.

Cloudflare 터널로 이 웹앱(http://localhost:8787)을 폰에서 열 수 있는 임시 주소를 만들어 줘.
cloudflared 가 없으면 설치부터 하고, 나오는 https 주소를 알려 줘. 접속 암호가 켜져 있는지도 확인해.

Claude는 winget install Cloudflare.cloudflared → cloudflared tunnel --url http://localhost:8787 을 실행하고 https://….trycloudflare.com 주소를 알려 줍니다. 도메인이 있으면 고정 주소도 만들 수 있습니다(파이스는 pais.sejong21c.com). 접속 암호가 꼭 켜져 있어야 합니다.

• 24시간 켜 두기: 파이스는 맥미니에서 상시 가동합니다(macOS launchd). 윈도우라면 아래처럼 요청합니다.

컴퓨터를 켜면 runner.js 가 자동으로 뜨게 해 줘. 관리자 권한 없이 되는 방법으로(시작프로그램), 이미 떠 있으면 두 번 띄우지 않게.

9단계 · MCP·커넥터 연결 — 세 가지 방향

MCP는 AI를 외부 앱·도구에 꽂는 표준 플러그이고, 커넥터는 그 MCP를 클릭 몇 번으로 연결하게 만든 것입니다. 한 번 꽂아 두면 "노션에 정리해 줘", "볼트에서 찾아 줘"가 말로 됩니다.

A. 데스크톱 앱(Code 탭)에 커넥터·플러그인 꽂기

1. 입력창 옆 + → Connectors 에서 Google Calendar · Slack · GitHub · Notion 등을 골라 연결합니다(로그인 창이 뜨면 허용).
2. 관리·해제는 Settings → Connectors, 또는 Connectors 메뉴의 Manage connectors.
3. 기능 묶음은 + → Plugins → Add plugin 에서 플러그인 브라우저로 설치합니다(스킬·MCP 서버 등이 함께 들어옴).
4. 목록에 없는 MCP 서버는 Claude에게 맡깁니다.

(서비스 이름) MCP 서버를 이 프로젝트에 연결해 줘. 주소는 (https://…/mcp) 야. 설정 파일에 추가하고, 로그인이 필요하면 방법을 알려 줘.

• 다른 도구에서는: Claude Code 터미널판 claude mcp add --transport http notion https://mcp.notion.com/mcp → /mcp 로 로그인 · Codex codex mcp(옵션은 codex mcp --help, [원격 서버 옵션 확인 필요]) · Antigravity 설정 → Customizations → Installed MCP Servers → Add MCP

B. claude.ai(웹·폰 채팅)에 커넥터 켜기

• 개인 Pro·Max: Customize → Connectors → + Add → 목록에서 Notion·Gmail 등을 고르거나 'Add custom connector'
• 팀·엔터프라이즈: 조직 소유자가 Organization settings → Connectors → Add → Custom → Web 으로 등록 → 직원은 각자 Customize → Connectors 에서 Connect
• 대화에서 켜기를 잊지 말 것: 입력창 왼쪽 아래 + → Connectors 에서 켭니다. 연결만 하고 안 켜면 "커넥터가 꺼져 있다"고 나옵니다.

C. 내 에이전트를 claude.ai 에 꽂기 (파이스 방식)

파이스는 서버에 /mcp 창구를 열어, 폰의 Claude 앱에서도 "볼트에서 울산복합 ITP 찾아줘"가 되게 했습니다(src/mcp.js, 외부 패키지 0).

• 원칙 ① 읽기 전용 도구만 연다(쓰기·실행은 절대 안 넣음, selftest가 목록을 못박음)
• 원칙 ② 주소에 무작위 비밀을 넣거나 로그인(OAuth)을 붙인다
• 원칙 ③ 누가·언제·어느 도구를 불렀는지만 기록(검색어는 안 남김)

server.js 에 /mcp 창구를 만들어 줘(MCP Streamable HTTP, JSON-RPC 2.0).
- 노출 도구는 읽기 전용 2개만: 문서 검색, 노트 읽기. 쓰기·실행 도구는 절대 넣지 마.
- 주소 뒤에 48자 무작위 비밀을 붙이고 비밀은 data/ 아래 파일에만 저장.
- 호출 기록(누가·언제·어떤 도구·성공 여부)만 남기고 검색어는 남기지 마.
- 노출 도구 목록을 셀프체크로 못박아 줘.

등록은 B의 'Add custom connector' 에 https://내주소/mcp-… 를 넣으면 됩니다. 그러면 데스크톱 앱의 Chat·Code 탭에서도 같은 커넥터를 씁니다. 지금 파이스 커넥터는 도구 10개를 엽니다: 문서 검색(search_docs) · 볼트 검색·노트 읽기 · 원본 읽기 · 파일 찾기 · 폴더 보기 · 표 목록·조회 · 기록 세기 · 색인 상태.

10단계 · 매일 굴리며 키우기

• 한 번에 하나: "이번에는 이것만" → 직접 확인 → 커밋. 파이스도 하루에 Phase 하나씩 했습니다.
• 고장은 재발 방지까지: 고친 뒤 "같은 고장을 잡는 검사를 selftest 에 넣어 줘".
• 문서는 코드에 있는 것만: 계획은 ROADMAP 에, 현재 구조는 ARCHITECTURE 에.
• 사용량 아끼기: 큰 파일은 필요한 부분만 읽게 하고, 화면 확인은 스크린샷보다 글로.
• 세션 나누기: 왼쪽 사이드바에서 새 세션을 열어 일을 나눕니다. 한 세션이 너무 길어지면 새로 시작하는 편이 빠릅니다.

자주 막히는 곳

• Code 탭을 누르면 업그레이드하라고 나온다 → 유료 플랜(Pro·Max·Team·Enterprise) 필요
• Code 탭에서 403 오류 → 로그아웃 후 다시 로그인하고 앱을 다시 켠다
• 명령 실행이 이상하다 → Git for Windows 를 설치한다(없으면 PowerShell 로 대신 실행됨)
• API 키를 입력창에 붙여 넣었다 → 즉시 키 재발급
• "고쳤다는데 화면이 그대로다" → 브라우저 캐시부터 의심(강력 새로고침, 다른 브라우저)
• 커넥터를 연결했는데 안 된다 → 대화 입력창 + → Connectors 에서 켰는지
• 문서의 숫자가 실제와 다르다 → 숫자는 코드에서 세게 하고 문서에는 박지 않는다

따라 만들기 체크리스트

• 한 문장 정의 + 청사진(docs/blueprint.md) + archify 구조도
• Claude 데스크톱 앱 설치 · 로그인 · Code 탭 · 작업 폴더 열기
• 규칙 파일(CLAUDE.md)
• 브라우저 패널(localhost:8787)에서 대화가 된다
• 도구 3개 + 실행 로그가 보인다
• 위험 권한은 기본 OFF 인지 확인했다
• 기억 · 백그라운드 잡 · 예약 실행
• 단계마다 git 커밋
• 폰에서 접속(접속 암호 켬)
• 커넥터 1개 이상 연결
• (마지막) 자기수정 + 구조대 되돌리기 확인