제가 고생하며 배운 모든 것 — 6주간의 시간, 잠 못 이루는 밤 :), 두 개의 환경, 그리고 실제로 작동하는 하나의 에이전트.

이야기 (The Story)

저는 6주 동안 처음부터 개인용 AI 에이전트를 구축하는 데 시간을 보냈습니다. 단순한 챗봇 래퍼 (chatbot wrapper)가 아니라, 작업을 관리하고, 거래를 추적하며, 이메일을 읽고, 비즈니스 데이터를 분석하며, 제가 놓칠 수 있는 것들을 선제적으로 제시하는 지속적인 어시스턴트 (assistant)를 만드는 과정이었습니다.

시작은 클라우드 (Claude Projects — 공유 메모리 파일, 풍부한 컨텍스트 윈도우 (context windows), 커스텀 스킬 (custom skills))에서였습니다. 그 후 VS Code 내부의 Claude Code로 마이그레이션(migration)했는데, 이를 통해 로컬 파일 접근, git 추적, 셸 훅 (shell hooks), 그리고 예약된 헤드리스 작업 (headless tasks)이 가능해졌습니다. 이 마이그레이션 과정은 우리가 인지하지 못했던 문제들을 해결하도록 강제했습니다.

이 100가지 팁은 그 정수입니다. 대부분은 진지한 에이전트 기반 설정 (agentic setup)에 보편적으로 적용됩니다. Claude 20배 성능 최대화는 필수입니다. 시작 단계에서는 100% 개발이었고 실제 업무는 0%였으나, 3주 후에는 50:50이 되었고, 지금은 약 20:80 정도입니다.

🏗️ 기반 및 정체성 (FOUNDATION & IDENTITY) (1–8)

1. 시스템 프롬프트 (system prompt)가 아닌 헌법 (Constitution)을 작성하세요.
시스템 프롬프트는 명령 목록입니다. 헌법은 규칙이 왜 존재하는지를 설명합니다. 에이전트가 어떤 규칙도 적용되지 않는 예외 상황 (edge case)에 직면했을 때, 추측하는 대신 헌법을 바탕으로 추론합니다. 이 단 하나의 차이가 우아하게 성능을 유지하는 에이전트와 자신 있게 환각 (hallucinate)을 일으키는 에이전트를 구분합니다.

2. 에이전트에게 단순한 라벨이 아닌 이름, 목소리, 그리고 역할을 부여하세요.
"항상 1인칭 사용. 직설적일 것. 감정보다 데이터 우선. 불필요한 문구 금지. 마지막 요약 금지." 이렇게 하면 세션당 수백 개의 미세한 결정 과정을 제거할 수 있으며, 감사 (audit) 가능한 일관성을 만들어냅니다. 정체성은 다른 모든 요소가 복리로 쌓이는 기반입니다.

3. 엄격한 규칙 (hard rules)과 행동 지침 (behavioral guidelines)을 분리하세요.
엄격한 규칙은 전용 섹션에 배치하며, 컨텍스트 (context)에 의해 절대 무시되지 않아야 합니다. 행동 지침은 상황에 따라 적응하는 기본값입니다. 이 둘을 섞으면 둘 다 무의미해집니다. 에이전트가 모든 것을 협상 가능한 것으로 취급하거나, 혹은 아무것도 협상할 수 없게 만들기 때문입니다.

4. 단순히 "사용자"를 정의하는 것이 아니라, 당신의 원칙(Principal)을 깊이 있게 정의하세요.
이 에이전트는 누구를 위해 봉사합니까? 그들을 좌절시키는 것은 무엇입니까? 그들은 어떻게 의사결정을 내립니까? 그들이 선호하는 커뮤니케이션 스타일은 무엇입니까? "직관이 아닌 데이터로 결정함. 단일 추천이 아닌 점수가 매겨진 대안을 원함. 모호한 답변을 싫어함." 이러한 정의는 그 어떤 프롬프트 엔지니어링 (Prompt Engineering) 기술보다 모든 응답의 형태를 결정짓습니다.

5. 역량 지도 (Capability Map)와 구성 요소 지도 (Component Map)를 별도로 구축하세요.
역량 지도 (Capability Map): 에이전트가 무엇을 할 수 있는가? (모든 기술, 통합, 자동화).
구성 요소 지도 (Component Map): 어떻게 구축되었는가? (어떤 파일이 존재하는가, 무엇이 무엇에 연결되어 있는가).
둘 다 필요합니다. 이 둘을 혼동하면 3개월 뒤에는 아무도 사용할 수 없는 문서를 만들게 됩니다.

6. 에이전트가 "아닌 것"을 정의하세요.
"요약기가 아님. 무조건 예스만 하는 기계가 아님. 검색 엔진이 아님. 질문을 기다리지 않음." 부정적인 정의는 긍정적인 정의만큼이나 강력하며, 특히 일반적인 도움을 주려는 성향으로 서서히 변질되는 것을 방지하는 데 효과적입니다.

7. 에이전트의 정체성에 "생각하기 (THINK) vs. 실행하기 (DO)" 멘탈 모델을 구축하세요.
불확실할 때 → 생각하기 (분석, 초안 작성, 준비 — 하지만 허가를 기다리느라 중단되지는 말 것). 확실할 때 → 실행하기 (실행, 작성, 발송). 에이전트는 결코 얼어붙어 있어서는 안 됩니다. 가장 리스크가 낮은 수준에서 행동을 기본값으로 설정하고 결과를 드러내세요. 마비된 에이전트는 쓸모가 없습니다.

8. 정체성 파일 (Identity File)을 git으로 버전 관리하세요.
행동이 변질될 때, 당신의 설정에 대해 git blame을 사용할 수 있어야 합니다. 행동의 퇴보 (Behavioral regressions)는 예상보다 더 자주 특정 편집 사항과 직접적으로 연결됩니다. 버전 기록이 없다면, 정체성 변질을 디버깅하는 것은 고고학 작업이 될 것입니다.

🧠 메모리 시스템 (9–18)

9. 메모리에는 데이터베이스가 아닌 평면 마크다운 (Flat Markdown) 파일을 사용하세요.
개인용 에이전트의 경우, 마크다운 파일이 벡터 데이터베이스 (Vector DB)보다 낫습니다. 읽기 쉽고, grep으로 검색 가능하며, git으로 추적할 수 있고, 에이전트가 직접 로드할 수 있습니다. 인프라도 필요 없고, 당신과 에이전트의 메모리 사이에 추상화 계층 (Abstraction Layer)도 필요 없습니다. 제대로 작동하는 가장 단순한 것이 대개 정답입니다.

10. 날짜가 아닌 도메인(Domain)별로 메모리를 분리하세요.
entities_people.md, entities_companies.md, entities_deals.md, hypotheses.md, task_queue.md. 파일 하나가 하나의 도메인이 되어야 합니다. 시간 순서대로 쌓아둔 데이터 덤프(Dumps)는 2주만 지나도 검색이 불가능해집니다.

11. MEMORY.md 인덱스 파일을 구축하세요.
모든 메모리 파일을 한 줄의 설명과 함께 나열하는 단일 인덱스 파일입니다. 에이전트는 인덱스를 먼저 로드한 다음, 필요에 따라 특정 파일을 가져옵니다. 이를 통해 컨텍스트 윈도우 (Context Window) 사용량을 예측 가능하게 유지하고 에이전트의 조회 속도를 빠르게 유지할 수 있습니다.

12. "캐시 (Cache)"와 "신뢰할 수 있는 단일 출처 (Source of Truth, SSOT)"를 명시적으로 구분하세요.
로컬의 deals.md는 CRM의 캐시입니다. CRM이 SSOT입니다. 모든 캐시 파일에 last_sync: 헤더를 표시하세요. 에이전트는 모든 분석 전에 데이터의 최신 상태를 알립니다: "데이터: 5월 11일자 CRM 내보내기, 경과 시간 8일." 오래된 데이터를 조용히 사용하는 것이 바로 '확신에 차 있지만 틀린' 결과가 발생하는 원인입니다.

13. 명시적인 TTL (Time To Live)을 가진 session_hot_context.md를 구축하세요.
지난 세션에서 진행 중이었던 작업은 무엇인가요? 보류 중인 결정은 무엇이었나요? 에이전트는 세션 시작 시 이 파일을 로드합니다. 72시간이 지나면 만료됩니다. 오래된 핫 컨텍스트 (Hot Context)는 컨텍스트가 없는 것보다 더 나쁩니다. 에이전트가 과거의 상태를 현재 상태인 것처럼 제시하기 때문입니다.

14. 비동기적 브레인 덤프 (Brain Dump) 버퍼로서 daily_note.md를 구축하세요.
하루 종일 떠오르는 생각, 음성-텍스트 변환 (Voice-to-text), 빠른 아이디어들을 여기에 던져 넣으세요. 에이전트는 동기화 루틴 중에 이를 처리하여 항목들을 올바른 위치로 라우팅(Routing)합니다. 캡처 시점의 마찰 없이 구조화된 메모리를 생성할 수 있습니다.

15. 신뢰 수준 (Confidence Levels)이 포함된 hypotheses.md 파일을 구축하세요.
지속적인 직감: "공급업체 X의 용량이 가득 찼을 수 있음 (신뢰도 65%)." 에이전트는 관련 주제가 나타날 때 이를 참조합니다. 이는 세션을 가로질러 지속되며 시간이 지남에 따라 검증되거나 부정되는 '의구심 계층 (Suspicion Layer)'을 형성합니다. 가설의 유효 기간은 30일로 설정하세요. 오래된 가설은 노이즈 (Noise)가 됩니다.

16. WAITING_ON_ME 큐 (Queue)를 구축하세요.
에이전트가 준비를 마쳤고 당신의 결정을 기다리고 있는 모든 항목을 타임스탬프와 함께 이곳에 배치합니다. 주간 검토를 수행하세요. 7일이 경과한 항목은 선제적인 알림 (Proactive nudge)을 보냅니다. 30일이 경과한 항목은 자동으로 종료 (Auto-closed) 처리합니다. 이는 열린 루프 (Open loops)가 소리 없이 사라지는 것을 방지합니다.

17. user_behavioral_profile.md를 구축하세요.
사용자가 무엇을 빠르게 승인하고 무엇을 느리게 승인합니까? 어떤 결정을 직관적으로 내리고 어떤 결정을 분석적으로 내립니까? 에이전트는 이를 사용하여 "자율적으로 행동할 것인가 vs. 에스컬레이션 (Escalate)할 것인가"를 결정합니다. 몇 달간의 관찰 후에는 놀라울 정도로 정확해집니다.

18. 메모리 폴더를 클라우드 스토리지에 미러링 (Mirror)하세요.
로컬 머신이 고장 나면 에이전트는 수개월 동안 축적된 지식을 잃게 됩니다. 메모리 폴더를 Dropbox/Drive/S3에 미러링하세요. 이는 백업 (Backup)이 아니라 생존 (Survival)의 문제입니다. 에이전트의 메모리는 시스템에서 가장 대체 불가능한 부분입니다.

📚 지식 라이브러리 (KNOWLEDGE LIBRARY) (19–23)

19. 날짜가 아닌 클러스터 (Cluster)별로 정리된 큐레이션된 지식 라이브러리를 구축하세요.
도메인 폴더(sales_negotiation/, strategy/, supply_chain/)에 책, 보고서, 참고 자료를 분류하세요. 탐색 허브로서 INDEX.md를 추가합니다. 에이전트는 인덱스를 먼저 검색한 다음 관련 소스를 가져옵니다. 문서를 단순히 평면적으로 쏟아부어 놓는 것은 무덤과 같지만, 구조화된 라이브러리는 살아있는 리소스가 됩니다.

20. 모든 주요 소스에 대해 .brief.md 파일을 구축하세요 — 게으르게 생성(Lazy-generate)하십시오.
책이나 보고서당 한 페이지로 구성합니다: 핵심 논지, 3~5개의 핵심 개념, 귀하의 맥락에 맞는 구체적인 적용 사례를 포함합니다. 처음부터 모든 브리프 (Brief)를 만들지 마세요. 실제로 해당 소스를 처음 사용할 때 각 브리프를 생성하십시오. 인용 형식은 전체 텍스트가 아닌 브리프를 링크합니다. 브리프는 재사용 가능한 산출물 (Artifact)이 됩니다.

21. 어떤 출처를 인용하기 전에 3가지 질문으로 구성된 품질 게이트 (Quality Gate)를 구축하십시오.
(1) 이것이 사용자가 제1원리 (First Principles)로부터 도출할 수 없는 무언가를 추가하는가? (2) 이것이 단순히 상황을 확인하는 것이 아니라, 상황을 재구성하는 구체적인 프레임워크 (Framework)를 제공하는가? (3) 이것을 제거했을 때 공백이 생기는가? 3개 중 2개 이상 해당하면 → 인용하십시오. 그렇지 않으면 → 침묵 속의 컨설팅 (Silent consultation)을 수행하십시오. 이 게이트는 최악의 인용 실패 모드, 즉 통찰력을 더하기 위해서가 아니라 노력을 증명하기 위해 인용하는 행위를 제거합니다.

22. "침묵 속의 컨설팅 (Silent consultation)"은 유효하며, 종종 더 나은 출력물입니다.
당신은 라이브러리를 확인하고 그 통찰력을 추론에 적용했지만, 이를 명시적으로 언급하지는 않았습니다. 출력물은 당신이 이를 참고했기에 더 날카로워졌지만, 인용하지 않았기에 군더더기가 없습니다. 이를 에이전트의 행동 방식에 명시적으로 구축하십시오. 사용자는 당신이 책을 펼쳤다는 사실이 아니라, 그 추론 과정으로부터 이득을 얻습니다.

23. 활성 프로젝트 및 주요 관계별로 지식 스택 (Knowledge stacks)을 사전 배선 (Pre-wire)하십시오.
각 활성 프로젝트에 대해: 프레임워크가 직접 적용되는 23개의 출처를 준비하십시오. 각 주요 연락처에 대해: 커뮤니케이션 스타일, 협상 또는 문화적 역학 관계를 위한 23개의 출처를 준비하십시오. 에이전트는 일반적인 "비즈니스 논의" 트리거가 아니라, 해당 컨텍스트가 활성화될 때 이를 자동으로 로드합니다. 사전 배선 (Pre-wiring)은 라이브러리 사용을 의도적인 행위가 아닌 반사적인 행위로 만듭니다.

🛠️ 기술 아키텍처 (SKILLS ARCHITECTURE) (24–31)

24. 각 기술을 SKILL.md 명세 (Spec)를 포함한 독립된 디렉토리로 구축하십시오.
인라인 프롬프트 (Inline prompts)로 만들지 마십시오. 폴더, 자기 문서화된 명세 파일, 명시적인 트리거 (Triggers), 명시적인 출력물 (Outputs), 그리고 명시적인 "사용 금지 (NOT FOR)" 조항을 갖추어야 합니다. 이렇게 하면 기술이 에이전트의 핵심 정체성을 건드리지 않고도 조합 가능하고, 감사 가능하며, 교체 가능해집니다.

25. 모든 기술에 명시적인 트리거 문구 (Trigger phrases)를 작성하십시오.
트리거: 사용자가 "inbox 처리" / "inbox 정리" / "내 inbox에 무엇이 있지"라고 말할 때 항상 실행. LLM이 기술을 언제 사용할지 추론하도록 의존하지 마십시오. 명시적인 문구 매칭 (Phrase matching)은 신뢰할 수 있는 활성화를 보장합니다. 추론 (Inference)은 신뢰를 떨어뜨리는 간헐적인 오작동을 야기합니다.

26. "NOT FOR" 섹션은 "FOR" 섹션만큼 중요합니다.
"NOT FOR: 가격 결정. NOT FOR: 법률 분석. NOT FOR: 재무적 약속." 이는 스킬 크리프 (Skill creep) — 표면적인 패턴 매칭 (Pattern-matching) 때문에 모든 것이 잘못된 스킬로 라우팅되는 느린 표류 현상을 방지합니다.

27. 스킬 (Skills)과 에이전트 (Agents)를 구분하십시오.
스킬은 절차적입니다 — 정의된 워크플로 (Workflow)와 예측 가능한 출력을 가집니다. 에이전트는 도메인 전문 지식을 가지고 판단 (Judgment calls)을 내립니다. 스킬은 단계를 오케스트레이션 (Orchestrate)하고, 에이전트는 결정합니다. 이 두 개념을 혼합하면 디버깅하기 어려운 신뢰할 수 없는 동작이 발생합니다.

28. 사용량 추적이 포함된 스킬 레지스트리 (Skills registry)를 구축하십시오.
스킬당 하나의 행을 생성합니다: 이름, 트리거 (Trigger), 목적, 마지막 사용일, KPI. 분기별 감사: 60일 동안 사용량이 없는 스킬은 더 나은 트리거 예시를 제공하거나 폐기 (Deprecated) 처리합니다. 사용되지 않는 스킬은 이점 없이 유지보수 부담만 가중시킵니다.

29. 다회차 정교화 (Multi-pass refinement)를 위한 /iterate 스킬을 구축하십시오.
생성 (PRODUCE) → 비판 (CRITIQUE) (점수 + 주요 격차) → 정교화 (REFINE) → 반복. 점수가 9/10에 도달하거나 정체기 (Plateau)에 도달하면 멈춥니다. 이를 통해 점수 진행 상황과 버전 차이 (Version deltas)를 확인할 수 있습니다. 이는 에이전트에게 단순히 "더 좋게 만들어줘"라고 요청하는 것과는 근본적으로 다릅니다. 이는 측정 가능한 진전이 있는 구조화된 개선 루프 (Improvement loop)입니다.

30. 모든 스킬에 출력 강도 (Output intensity) 수준을 구축하십시오.
최소 (MINIMAL, 빠른 요약), 표준 (STANDARD, 구조화됨), 전체 (FULL, 풍부한 결과물). 스킬은 컨텍스트 (Context)에 적응합니다. 예/아니오 질문에 대해 5페이지 분량의 분석을 내놓는 것은 스킬 설계의 실패입니다. 강도는 질문의 비중에 맞아야 합니다.

31. 발견 가능성을 위해 눈에 보이는 Outbox 폴더를 구축하십시오.
깊은 파일 구조는 조직화에는 적합하지만 발견 가능성 (Discoverability) 측면에서는 최악입니다. 모든 출력 파일은 눈에 보이는 Outbox/ 폴더에 동시에 복사됩니다. 주기적으로 비워주십시오. Outbox가 없으면 사용자는 에이전트가 방금 생성한 것을 찾기 위해 전체 트리 구조를 탐색해야 합니다.

🤖 멀티 에이전트 및 협의체 (MULTI-AGENT & COUNCIL) (32–41)

32. 명시적인 에이전트 디스패치 매트릭스 (agent dispatch matrix)를 구축하세요.
[요청 내 시그널] → [할당할 에이전트] 형태의 테이블을 만드세요. 예: 가격 / 공급업체 / 배송 → 조달 에이전트 (procurement agent)