나의 AI 비서 Sancho 만들기 - 1편 에이전트 AI 만들기

개인 에이전트 AI 강좌 · 1 / 10편

© 2026 crazy4eu (cwkim83) · 강좌 자료 CC BY-NC-ND 4.0 · 코드 상업적 배포 금지 — 맨 아래 「저작권 · 라이선스」
💻 완성 소스: github.com/cwkim83/my-agent-Sancho (태그 ep1) — 막히면 이 코드를 열어 비교해 보세요.
단계 번호는 영상 왼쪽 위 장면 이름과 같고, "영상 시각"은 편집본 기준입니다. 회색 상자는 Code 탭 입력창에 그대로 붙여 넣는 요청문입니다.
다음 편: 나의 AI 비서 Sancho 만들기 - 2편 대시보드와 일정

핵심 요약

한 줄 요약 — 코드를 한 줄도 쓰지 않고, 청사진 → 구조도 → 규칙 파일 → 서버·로그인 → 화면 → 두뇌 → 기억 → 검증 순서로 말로만 만듭니다.

1편 · 에이전트 AI 만들기

목적

로그인 되는 나만의 AI 비서의 뼈대를 만듭니다. 화면과 두뇌를 먼저 갖추고, 2편부터 업무 화면(대시보드·일정·프로젝트…)을 하나씩 붙입니다.

준비물

• Claude 계정 + 유료 요금제(Pro·Max·Team) — 개인 계정이면 됩니다
• Claude 데스크톱 앱 (claude.com/download) — Claude Code 가 들어 있어 따로 설치하지 않습니다
• Node.js 18 이상, Git — 없으면 2단계에서 Claude 가 설치 방법을 알려 줍니다
• 빈 폴더 하나 (예: 문서 폴더 안의 my-agent)

만드는 단계

0단계 · 여는 말 (영상 0:05)

• 오늘 만들 것: 로그인 화면 → 왼쪽 업무 메뉴 + 가운데 채팅창 → 내 Claude Code 가 답하는 비서 → 기억까지.
• 만드는 도구는 Claude 데스크톱 앱의 Code 탭 하나. 일은 가볍고 빠른 Sonnet 5.5 가, 마지막 검증은 더 꼼꼼한 Opus 5.5 가 합니다(사용량은 아끼고 품질은 지키는 방법).

1단계 · 준비 — 앱과 작업 폴더 (영상 0:46)

1. 파일 탐색기에서 빈 폴더를 만듭니다(영상: 문서\AI교육\my-agent).
2. Claude 앱 위쪽 Code 탭 → 환경 Local → 폴더 선택으로 방금 만든 폴더를 엽니다.
3. 전송 버튼 옆에서 모델 Sonnet 5.5, 권한 모드 수동을 고릅니다.

• 수동 = 파일을 고치거나 명령을 실행하기 전에 매번 물어보는 모드. 처음엔 이걸로 무엇을 하는지 보면서 배웁니다.

2단계 · 첫 요청 — 준비물 확인 (영상 1:23)

나는 코드를 모른다. 쉬운 말로 설명해 줘.
이 PC 에 Node.js(18 이상)와 Git 이 설치돼 있는지 확인해 줘. 없으면 무엇을 어떻게 설치하는지 알려 줘.
그다음 이 폴더를 git 저장소로 만들어 줘.

• 명령을 실행하기 전에 "허용하시겠습니까?" 창이 뜹니다. 무엇을 실행하는지 읽어 보고 한 번만 허용을 누릅니다.
• 영상에서는 Node.js 24 와 Git 이 이미 있어서 설치할 것이 없었고, 폴더가 git 저장소가 됐습니다.
• git = 작업을 단계마다 저장해 두는 장치. 잘못되면 앞 단계로 되돌릴 수 있어서 처음부터 켜 둡니다.

3단계 · 청사진 (영상 1:54)

내가 만들 앱의 청사진을 docs/blueprint.md 로 써 줘.
- 이름: 나의 AI 비서(my-agent) Sancho
- 무엇: 내 PC 에서 도는 개인 AI 비서 + 업무 대시보드. 브라우저에서 로그인해서 쓴다.
- 두뇌: 이 PC 에 설치된 Claude Code 를 그대로 쓴다(내 구독 로그인, API 키 없음).
- 데이터: 데이터베이스 서버 없이 data/ 폴더의 JSON·마크다운 파일. data/ 는 git 에 올리지 않는다.
- 외부 패키지 없이 Node.js 내장 기능만.
- 화면: 왼쪽 메뉴(대시보드·일정·프로젝트·WBS·메일·메신저·회의록·결재·목표·공수·지식노트·워크플로·설정), 대시보드 자리에 AI 채팅.
- 절대 안 할 것: 메일 자동 발송, 파일 삭제를 묻지 않고 하기, 회사 밖으로 자료 보내기.
- 로드맵 10편: 1 로그인·채팅·두뇌·기억 / 2 대시보드·일정 / 3 프로젝트·WBS / 4 예약·알림 / 5 메일·문서 / 6 메신저·회의록 / 7 결재·목표·공수 / 8 안전장치 / 9 밖에서 쓰기·커넥터·음성 / 10 지식노트·워크플로
어려운 용어는 괄호로 쉽게 풀어 줘.

• 가장 중요한 단계입니다. AI 는 시키는 대로 만들어서, 목표가 흐리면 엉뚱한 걸 아주 빨리 만듭니다. 코드를 시키기 전에 무엇을·왜·어디까지 만들지 먼저 적습니다.
• "절대 안 할 것"은 나중에 안전장치(8편)의 기준이 됩니다.
• 결과: docs/blueprint.md 가 생기고, "data/ 는 git 에 안 올린다"는 말에 맞춰 .gitignore(git 이 무시할 목록)까지 알아서 만듭니다.

4단계 · 구조도 (archify) (영상 2:33)

영상에서는 세 번에 나눠 말했지만(① 설치 명령 거부 → "이미 있으니 건너뛰어" ② 브라우저 패널이 한글 파일 이름을 못 엶 → 영어 이름으로), 처음부터 이렇게 쓰면 한 번에 됩니다.

archify 스킬로 docs/blueprint.md 의 전체 구조도(architecture)를 그려 줘.
archify 가 없으면 npx skills add tt-a1i/archify -g 로 설치하고, 이미 설치돼 있으면 설치는 건너뛰어.
브라우저 → server.js(로그인·화면·저장소·예약) → Claude Code(두뇌) → data/ 폴더(기억·예약·업무 데이터) 흐름이 보이게,
Claude Code → data/ 선도 넣고, 한국어 라벨로.
검증(validate)까지 통과시킨 뒤 docs/architecture.html 로 저장하고 브라우저 패널로 보여 줘.
검증하면서 생긴 docs/*.visual-check.* 파일은 .gitignore 에 넣어 줘.

• archify = 말로 설명하면 검증된 구조도를 그려 주는 스킬. 처음엔 글자가 상자와 겹쳐 검증에 실패했지만, 스스로 고쳐 9개 검사를 모두 통과했습니다.
• 읽기 명령마다 허락을 묻는 게 번거로워서, 영상은 이 단계에서 권한 모드를 자동으로 바꿨습니다. 자동은 안전한 일은 알아서 하고, 위험해 보이는 일만 멈춰서 묻습니다.
• 그림 보는 법: 브라우저 → 서버 → Claude Code → data 폴더. 앞으로 무엇을 만들든 "이 그림의 어디에 붙나"부터 생각하면 길을 잃지 않습니다.

5단계 · 일하는 법 파일 CLAUDE.md (영상 3:35)

CLAUDE.md 를 만들어 줘. 내용:
- 나는 코드를 모른다. 설명은 쉬운 한국어로, 결론부터.
- 시작할 때마다 docs/blueprint.md 와 docs/architecture.html 을 먼저 읽는다.
- 한 번에 한 단계만 하고, 끝나면 내가 직접 확인할 방법을 알려 준다.
- 기능을 만들면 그 기능을 검사하는 selftest 항목도 같이 만든다(node selftest.js).
- 외부 패키지 금지, Node.js 내장 기능만.
- 비밀번호·키는 코드나 대화에 쓰지 않는다. data/ 는 git 에 올리지 않는다.
- 단계가 끝나면 git 커밋, 메시지에 왜 바꿨는지 한국어로.

• Claude Code 는 매번 처음 보는 사람처럼 일합니다. 일하는 법을 CLAUDE.md 에 적어 두면 매번 먼저 읽고 따릅니다.
• 특히 "기능마다 검사(selftest)도 같이" — 비서가 커져도 이 검사가 망가진 곳을 먼저 찾아 줍니다.

6단계 · 서버와 로그인 화면 (영상 3:57)

server.js 를 만들어 줘. 외부 패키지 없이 Node.js 내장 http 로.
- 주소: http://127.0.0.1:8790 (이 PC 에서만 열린다)
- 화면 파일은 public/ 에서 내보낸다.
- 로그인: 계정이 하나도 없으면 첫 화면이 "관리자 계정 만들기"(이름·아이디·비밀번호 8자 이상).
  비밀번호는 scrypt 해시로 data/users.json 에 저장, 평문 저장 금지.
  로그인하면 세션 쿠키(HttpOnly, 30일), 로그아웃 버튼. 로그인 안 하면 /api 는 전부 401.
  틀린 비밀번호를 10번 넘게 치면 10분 잠금.
- public/login.html: 깔끔한 흰색 톤, 가운데 카드, 앱 이름 "나의 AI 비서 Sancho".
- .gitignore 에 data/ 를 넣는다.
- 실행용 start.bat(더블클릭하면 서버 켜고 브라우저 열기)도 만들어 줘.
- 다 되면 서버를 켜고 브라우저 패널로 로그인 화면을 보여 줘.
  그리고 가상 관리자(이름 홍길동, 아이디 demo, 연습용 비밀번호 sancho-demo-2026)로 계정을 만들고 로그인까지 해 줘. 새로고침해도 로그인이 유지되는지도 확인해 줘.

• 서버 = 비서의 몸통. 화면을 보여 주고, 로그인을 확인하고, 나중에는 두뇌에 일을 넘깁니다.
• 비밀번호는 해시로 바꿔 저장해서, 파일을 누가 열어 봐도 비밀번호를 알 수 없습니다.
• 결과: 비서가 가상의 홍길동 계정을 만들고 로그인까지 직접 확인했고, 점검 19개가 모두 통과했습니다. 연습용 비밀번호는 연습용일 뿐, 실제 비밀번호는 요청문에 절대 쓰지 않습니다.

7단계 · 메인 화면과 채팅창 (영상 4:39)

로그인하면 보이는 메인 화면 public/index.html 을 만들어 줘.
- 왼쪽 메뉴: 대시보드·일정·프로젝트·WBS·메일·메신저·회의록·결재·목표·공수·지식노트·워크플로·설정. 아직 없는 메뉴는 "준비 중" 화면.
- 위쪽: 앱 이름, 사용자 이름 칩(누르면 로그아웃).
- 대시보드 자리는 AI 채팅: 대화 목록(＋ 새 대화), 말풍선, 아래 입력창(Enter 전송, Shift+Enter 줄바꿈), 생각하는 동안 전송 버튼이 ■(중지)로.
- 답은 글자가 오는 대로 흘러나오게(서버에서 SSE 로 스트리밍). 마크다운 표·목록·코드가 보이게.
- 흰색 톤, 업무 플랫폼처럼 깔끔하게. 휴대폰 폭에서도 깨지지 않게.
- 아직 두뇌는 연결하지 말고, 서버가 "준비 중입니다"라고 한 글자씩 흘려보내는 가짜 답으로 화면만 먼저 확인하게 해 줘.
다 되면 브라우저 패널에서 "안녕" 을 보내서 가짜 답이 흘러나오는 걸 보여 줘.

• 앞으로 만들 메뉴를 미리 다 적어 두고, 없는 건 "준비 중"으로. 앱 전체 모양이 처음부터 보입니다.
• 두뇌를 붙이기 전에 일부러 가짜 답으로 화면부터 확인합니다. 화면 문제와 두뇌 문제가 섞이면 원인을 찾기 어렵습니다 — 한 번에 하나씩, 바이브 코딩의 첫째 규칙.
• 브라우저 패널이 좁으면 휴대폰 배치로 보입니다(휴대폰에서도 깨지지 않게 만들라고 했기 때문).

8단계 · 두뇌 연결 — Claude Code (영상 5:09)

이제 채팅의 두뇌를 이 PC 의 Claude Code 로 연결해 줘.
- 서버가 claude 를 실행한다: claude -p --output-format stream-json --verbose --include-partial-messages --model sonnet
  작업 폴더(cwd)는 data/, 사용자 말은 명령줄 인자가 아니라 표준입력으로 넘긴다.
- 허용 도구는 --allowedTools Read Glob Grep Edit Write WebSearch WebFetch 만(명령 실행은 아직 안 줌).
- 스트림의 글자(text_delta)는 화면에 흘려보내고, 도구를 쓰면 "⏺ 파일 읽는 중" 같은 줄로 보여 준다.
- 대화를 이어가도록 결과의 session_id 를 저장했다가 다음 말에 --resume 으로 넘긴다. ＋ 새 대화는 새 세션.
- ■ 중지를 누르면 claude 프로세스를 끈다.
- 중요: 이 서버를 Claude Code 세션 안에서 켜면 CLAUDECODE 같은 환경변수가 자식 claude 에 넘어가 "로그인 안 됨"이 난다.
  claude 를 실행할 때 CLAUDE 로 시작하는 환경변수와 ANTHROPIC_BASE_URL 을 지우고 실행해.
- 로그인이 안 돼 있거나 사용 한도에 닿으면 쉬운 한국어로 알려 줘.
- 화면 확인용으로 넣었던 /md 장치는 지워 줘.
- 다 되면 서버를 다시 켜고, 브라우저 패널에서 "안녕, 너는 누구야?"로 시험해 줘.

• 비서는 내가 쓰는 Claude Code 를 그대로 불러서 생각합니다. API 키도, 따로 내는 요금도 없이 내 구독 그대로.
• 비서에게는 파일 읽기·쓰기·웹 검색만 허락했습니다. 명령 실행 같은 위험한 능력은 8편에서 안전장치와 함께 켭니다.
• 영상은 이 단계가 12분쯤 걸려서 빨리 감기로 보여 줍니다. 비서가 Claude Code 를 실제로 불러 보고, 막히는 곳을 고치고, 점검까지 만듭니다.
• 결과: "저는 Sancho(산초), 사용자님의 AI 비서예요"가 한 글자씩 흘러나옵니다.

9단계 · 기억 (영상 5:55)

비서에게 성격과 기억을 붙여 줘.
- data/.system.md 를 만들어 claude 실행 때 --append-system-prompt-file 로 넘긴다(지금 붙인 짧은 안내는 이 파일로 옮겨). 내용:
  너의 이름은 Sancho, 주인의 개인 AI 비서. 한국어로 짧고 정확하게. 오늘 날짜와 주인 이름을 알려 준다.
  주인이 "기억해: …" 하면 data/memory.md 에 "- 날짜 내용" 한 줄을 덧붙인다. "잊어: …" 하면 그 줄을 지운다.
  대화에서 오래 쓸 만한 사실(주인의 직책·선호·반복 업무)을 알게 되면 묻지 않아도 memory.md 에 적고 답 끝에 "(기억함)" 표시.
  답하기 전에 memory.md 를 읽고 반영한다.
- 채팅 왼쪽에 "기억" 칸: memory.md 내용을 보여 주고 줄마다 삭제 버튼.
- selftest.js 에 로그인·비밀번호 해시·세션·기억 파일 검사 항목을 넣고 node selftest.js 로 돌려 줘.
다 되면 브라우저 패널에서 "기억해: 나는 가나다전자 품질관리부 부장이고, 보고서는 표로 받는 걸 좋아해" 를 보내고, ＋ 새 대화에서 "내가 누구고, 보고서는 어떻게 받는 걸 좋아하지?" 로 시험해 줘.

• 방법은 단순합니다. "기억은 memory.md 에 한 줄씩 적어라"고 일러두면, 비서가 원래 가진 파일 쓰기 능력이 그대로 기억 기능이 됩니다. 도구를 따로 만들지 않습니다.
• 결과: 새 대화인데도 "가나다전자 품질관리부 부장, 보고서는 표로"를 기억해서 답했습니다. 점검 51개 통과.

10단계 · Opus 로 검증 (영상 6:23)

전송 버튼 옆 모델을 Opus 5.5 로 바꾼 뒤 보냅니다.

지금까지 만든 것을 검증해 줘. 고치기 전에 무엇이 문제인지 먼저 목록으로 보여 줘.
- 로그인 없이 /api 나 화면 데이터에 접근되는 곳이 있는지
- 비밀번호가 평문으로 남는 곳(로그·파일)이 있는지
- data/ 밖의 파일을 읽고 쓰게 되는 경로가 있는지
- claude 실행이 실패했을 때 화면이 멈추지 않는지
- selftest 가 이 항목들을 실제로 잡는지
문제가 있으면 고치고 selftest 를 다시 돌려 줘.

• 모델을 바꾸면 경고가 뜹니다 — 지금까지의 대화를 새 모델이 다시 읽어야 해서 사용량을 조금 더 쓴다는 뜻입니다. 그대로 진행합니다.
• Opus 가 찾아 고친 6건: ① [심각] 두뇌가 data/ 밖 파일을 읽고 쓸 수 있었음 → data/ 안으로만 ② 주소의 대소문자만 바꾸면 로그인 없이 화면이 열림 ③ 다른 웹사이트가 내 브라우저를 거쳐 계정 만들기·로그인을 보낼 수 있었음 ④ 서버가 꺼졌을 때 새 대화 첫 말이 사라짐 ⑤ claude 가 바로 실패하면 화면이 ■ 에 멈춤 ⑥ 점검 빈틈 → 51개에서 74개로.
• 소넷이 만든 걸 오퍼스가 잡아냈습니다. 만드는 일은 빠른 모델, 따지는 일은 꼼꼼한 모델. 검증이 끝나면 다시 Sonnet 5.5 로 돌려 둡니다.

11단계 · 커밋하고 마무리 (영상 7:04)

지금까지를 git 커밋하고 ep1 태그를 붙여 줘. 메시지는 "1편: 로그인·채팅·두뇌(Claude Code)·기억".

• 커밋 = 게임의 세이브 포인트. 다음 편에서 뭔가 잘못돼도 여기로 돌아올 수 있습니다. 태그 = 세이브 포인트에 붙인 이름(ep1).
• 오늘 만든 코드는 github.com/cwkim83/my-agent-Sancho 의 ep1 태그에 있습니다.

💡 설명

• 청사진: 무엇을·왜·어디까지 만들지 적은 문서(docs/blueprint.md). AI 에게 주는 설계도.
• 구조도 · archify: 부품이 어떻게 이어지는지 그린 그림. archify 는 그 그림을 검증까지 해서 그려 주는 Claude Code 스킬.
• CLAUDE.md: Claude Code 가 매번 먼저 읽는 "일하는 법" 파일.
• 권한 모드: 수동(매번 물음) · 편집 자동 수락(파일 수정만 알아서) · 자동(위험한 일만 물음) · 계획(고치지 않고 계획만).
• 해시(scrypt): 비밀번호를 되돌릴 수 없는 글자로 바꿔 저장하는 방법.
• 127.0.0.1: "이 컴퓨터 자신"이라는 주소. 이 PC 안에서만 열립니다(밖에서 쓰는 방법은 9편).
• 스트리밍(SSE): 답을 다 만든 뒤가 아니라 글자가 오는 대로 화면에 흘려보내는 방식.
• 세션 · --resume: 대화를 이어 가게 하는 번호. 새 대화는 새 세션.
• selftest: 만든 기능이 제대로 도는지 한 번에 검사하는 파일(node selftest.js).
• git · 커밋 · 태그: 작업 저장 장치 · 저장 한 번 · 저장에 붙인 이름.

자주 막히는 곳

• archify 설치 명령을 거부한다 → 이미 설치돼 있는 경우입니다. "이미 있으니 설치는 건너뛰고 그려 줘"라고 말합니다.
• 브라우저 패널이 HTML 을 못 연다 → 폴더 경로에 한글이 있으면 생깁니다. "파일 이름을 영어로 바꿔서 열어 줘", 그래도 안 되면 "미리보기 서버로 열어 줘".
• 읽기 명령마다 허락을 묻는다 → 권한 모드를 자동으로 바꿉니다.
• 채팅에 "로그인 안 됨"이 뜬다 → "CLAUDE 로 시작하는 환경변수를 지우는 부분이 실제로 적용됐는지 확인하고 고쳐 줘".
• 명령이 멈춘 채 끝나지 않는다 → "멈춘 그 명령만 꺼 줘"라고 말합니다.
• 미리보기에서 로그인이 풀려 보인다 → 주소를 localhost 대신 http://127.0.0.1:8790 으로 엽니다(쿠키가 주소별로 따로).

됐는지 확인하는 방법

• start.bat 을 더블클릭하면 브라우저에 로그인 화면이 뜬다
• 로그인 → 새로고침해도 로그인이 유지되고, 이름 칩을 누르면 로그아웃된다
• 채팅에 "안녕, 너는 누구야?" → 답이 한 글자씩 흘러나온다
• "기억해: …" 뒤 ＋ 새 대화에서 물어도 기억대로 답한다
• node selftest.js → 모두 통과
• 로그아웃 상태에서 http://127.0.0.1:8790/Index.html → "없는 페이지"

스스로 점검

• 청사진을 먼저 쓰는 이유를 설명할 수 있다
• 권한 모드(수동·자동)의 차이를 알고 골랐다
• 두뇌를 붙이기 전에 가짜 답으로 화면부터 확인하는 이유를 안다
• 요청문에 실제 비밀번호·키를 쓰지 않았다
• 모델을 Opus 로 바꿔 검증하고, 다시 Sonnet 으로 돌려 놓았다
• ep1 태그로 커밋했다