Claude Code를 진짜 Agent처럼 쓰려면, 플러그인보다 Workspace가 먼저였다

요즘 Claude Code를 쓰다 보면 자연스럽게 이런 생각을 하게 됩니다.

“좋다는 MCP를 더 붙이면 Claude가 더 똑똑해지지 않을까?”

“Skills를 많이 설치하면 진짜 에이전트처럼 움직이지 않을까?”

“자동화 플러그인을 붙이면 내가 덜 신경 써도 되지 않을까?”

“서브에이전트를 여러 개 만들면 알아서 역할 분담을 잘하지 않을까?”

저도 처음에는 Claude Code를 더 잘 쓰는 방법이

더 많은 도구, 더 많은 플러그인, 더 많은 자동화를 붙이는 방향이라고 생각했습니다.

그런데 이번 강의 내용을 정리하면서 관점이 많이 바뀌었습니다.

핵심은 Claude Code를 강력하게 만드는 것은 플러그인 수가 아니라, AI가 일할 수 있는 작업 환경을 어떻게 설계하느냐였습니다.

강의에서 가장 인상 깊었던 문장은 이 흐름이었습니다.

> 좋은 Agent는 플러그인 수가 아니라, 목적 있는 작업장과 업데이트 루프에서 나온다.

여기서 말하는 작업장이 바로 Workspace입니다.

Claude Code를 그냥 실행하고 “이거 만들어줘”라고 하면,

AI는 어느 정도 결과를 만들어낼 수 있습니다.

하지만 그 결과가 항상 내가 원하는 방향으로 가는 것은 아닙니다.

- 어떤 문서를 기준으로 판단했는지 알기 어렵고

- 어떤 스킬을 써야 하는지 매번 설명해야 하고

- 긴 대화가 누적되면서 컨텍스트가 무거워지고

- 세션이 끝난 뒤 다음 작업으로 자연스럽게 이어지지 않고

- 작업 중 바뀐 기준이 다시 문서에 반영되지 않는 문제가 생깁니다.

그래서 이번 사례의 핵심은 단순합니다.

**Claude Code를 Agent처럼 쓰고 싶다면, 먼저 Agent가 일할 Workspace를 만들어야 한다.**

이 Workspace 안에는 단순히 코드 파일만 있는 것이 아닙니다.

- PRD

- CLAUDE.md

- Skills

- Knowledge Index

- 작업 규칙

- 토큰 관리 기준

- Wrap-up / Handoff 규칙

이런 것들이 함께 있어야 Claude Code가 “내가 원하는 방식”으로 일하기 시작합니다.

# 진행 방법

이번 정리는 “Workspace를 제대로 세팅해서 Claude Code를 진짜 Agent처럼 작동하도록 만드는 방법”에 대한 강의와 인포그래픽을 바탕으로 했습니다.

처음에는 Claude Code의 고급 사용법 정도로 생각했지만, 정리해보니 내용의 중심은 훨씬 더 넓었습니다.

단순히 CLAUDE.md를 잘 쓰는 법이 아니라,

AI가 일하는 환경 전체를 설계하는 법에 가까웠습니다.

제가 이해한 전체 흐름은 다음과 같습니다.

PRD 작성
→ 목적별 Workspace 생성
→ CLAUDE.md 작성
→ Skills 연결
→ Knowledge Index 구성
→ Claude Code 작업 실행
→ Wrap-up / Handoff
→ PRD, CLAUDE.md, Skills 업데이트

이 구조가 반복되면 Workspace는 단순한 폴더가 아니라,
점점 더 나의 작업 방식이 반영된 Agent처럼 변해갑니다.

1. 하네스는 AI를 내 의도대로 움직이게 하는 장치다

강의에서 가장 먼저 나온 개념은 하네스였습니다.

하네스는 원래 강아지나 말을 원하는 방향으로 이끌기 위해 사용하는 장치입니다.
AI에서의 하네스도 비슷합니다.

AI가 멋대로 흘러가지 않도록
목적, 제약, 역할, 지식, 출력 방식, 작업 순서를 잡아주는 장치입니다.

이때 하네스는 단순한 프롬프트 하나가 아닙니다.

예를 들면 이런 것들이 모두 하네스에 들어갑니다.

• CLAUDE.md

• AGENTS.md

• GEMINI.md

• Cursor rules

• 프로젝트 설명 문서

• PRD

• 폴더 구조

• 파일 네이밍 규칙

• 작업 순서

• 출력 형식

• 참고해야 할 지식 문서

• Knowledge Index

• Skills

• MCP

• hooks

• Wrap-up 규칙

처음에는 하네스를 “프롬프트를 잘 쓰는 기술” 정도로 생각할 수 있습니다.

하지만 실제로는 더 넓습니다.

프롬프트가 Claude에게 한 번 말로 지시하는 것이라면,
하네스는 Claude가 계속 참고할 수 있는 작업 환경의 기준을 만드는 일입니다.

예를 들어 이런 차이가 있습니다.

단순 프롬프트:
너는 뛰어난 개발자야. 이 기능을 만들어줘.

하네스 기반 작업:
이 Workspace는 SaaS 제품 개발용이다.
먼저 00_META/PRD.md를 읽고,
10_KNOWLEDGE/index.md에서 관련 문서를 확인한 뒤,
20_SKILLS/feature-implementation/SKILL.md 절차에 따라 작업한다.
작업 후에는 session-wrapup.md에 변경 사항과 다음 작업을 정리한다.

두 방식 모두 Claude에게 일을 시키는 것이지만, 결과의 안정성은 크게 달라질 수밖에 없습니다.

2. 기본 하네스와 런타임 하네스를 구분해야 한다

강의에서는 하네스를 크게 두 가지로 나눠서 볼 수 있었습니다.

하나는 기본 하네스이고,
다른 하나는 런타임 하네스입니다.

기본 하네스는 Claude가 작업 전에 읽고 따르는 정적인 기준입니다.

기본 하네스 예시

- CLAUDE.md
- AGENTS.md
- 프로젝트 문서
- PRD
- 폴더 구조
- rules
- 지식 문서
- Knowledge Index
- 작업 규칙

반면 런타임 하네스는 실행 중에 자동으로 개입하는 장치입니다.

런타임 하네스 예시

- MCP 서버
- hooks
- Skills 자동 실행
- slash commands
- 자동 트리거
- 에이전트 오케스트레이션
- OMC / OMX류 플러그인

런타임 하네스는 강력합니다.
잘 쓰면 반복 작업을 줄이고, 자동으로 필요한 도구를 불러오고, 여러 단계의 작업을 이어갈 수 있습니다.

하지만 강의에서는 초보자에게 런타임 하네스를 무조건 추천하지 않았습니다.

이유는 명확했습니다.

Claude Code를 아직 통제하지 못하는 상태에서 자동화부터 붙이면, 사용자가 AI에게 일을 시키는 것이 아니라 AI 자동화에 끌려가게 될 수 있기 때문입니다.

겉으로는 뭔가 자동으로 잘 되는 것처럼 보일 수 있습니다.
하지만 실제로는 이런 문제가 생길 수 있습니다.

• 어떤 MCP가 왜 실행됐는지 모른다.

• 어떤 Skill이 어떤 기준으로 선택됐는지 모른다.

• 결과가 왜 그렇게 나왔는지 설명하기 어렵다.

• 토큰은 많이 쓰는데 품질은 안정적이지 않다.

• 문제가 생겼을 때 어디를 고쳐야 할지 모른다.

그래서 강의의 메시지는 분명했습니다.

자동화를 늘리기 전에, 먼저 내가 통제할 수 있는 Workspace를 만들어야 한다.

3. 토큰과 컨텍스트는 반드시 관리해야 하는 운영 자원이다

이번 내용에서 현실적으로 가장 크게 와닿은 부분은 토큰 관리였습니다.

Claude Code를 쓰다 보면 기능 추가에만 집중하기 쉽습니다.

“이 MCP도 좋아 보이는데?”
“이 Skill도 설치해두면 언젠가 쓰지 않을까?”
“서브에이전트가 많으면 더 똑똑해지겠지?”

하지만 강의에서는 이렇게 경고했습니다.

MCP, Skills, 에이전트 자동화는 편하지만, 기본 토큰 사용량을 계속 늘릴 수 있다.

특히 아래와 같은 상태를 조심해야 합니다.

• 남들이 좋다는 MCP를 다 설치한다.

• 실제로 쓰지 않는 MCP도 계속 켜둔다.

• Skills를 100개씩 깔아둔다.

• 어떤 Skill이 언제 실행되는지 모른다.

• CLAUDE.md가 너무 길다.

• 긴 대화를 한 세션에 계속 누적한다.

• 긴 요구사항을 매번 채팅창에 붙여넣는다.

이렇게 되면 Claude Code는 시작부터 너무 많은 문맥을 끌어안게 됩니다.

결국 사용자는 “AI가 더 똑똑해졌다”고 느끼기보다,
“왜 이렇게 느려졌지?”, “왜 엉뚱한 걸 참고하지?”, “왜 토큰이 이렇게 많이 나가지?”를 겪을 수 있습니다.

그래서 강의에서는 기준을 단순하게 잡았습니다.

토큰 관리 기준

- 진짜 필요한 MCP만 남긴다.
- 일주일 이상 쓰지 않는 MCP나 Skill은 기본 연결에서 뺀다.
- 다시 필요하면 그때 설치하거나 연결한다.
- CLAUDE.md는 길게 쓰기보다 역할과 경로를 명확하게 쓴다.
- 긴 입력은 채팅창이 아니라 파일로 넘긴다.
- 세션이 길어지면 Wrap-up 또는 Handoff를 만든다.

특히 인상 깊었던 실무 기준은 이것이었습니다.

10줄이 넘어가는 내용은 채팅창에 붙여넣지 말고 파일로 만들어 넘긴다.

예를 들어 요구사항이 길다면 이렇게 하는 것이 더 좋습니다.

나쁜 방식:
채팅창에 긴 요구사항을 계속 복사해서 붙여넣기

좋은 방식:
00_META/PRD.md에 요구사항을 정리하고
Claude에게 해당 파일을 읽게 하기

이 방식은 단순히 토큰을 아끼기 위한 것이 아닙니다.

요구사항이 파일로 남기 때문에
다음 세션에서도 이어서 볼 수 있고,
작업이 끝난 뒤 무엇이 바뀌었는지도 비교할 수 있습니다.

4. Workspace는 단순 폴더가 아니라 Agent의 몸체다

이번 강의에서 가장 중요한 관점은 Workspace as Agent였습니다.

보통 Agent라고 하면 별도의 AI 에이전트나 서브에이전트를 떠올리기 쉽습니다.

예를 들면 이런 식입니다.

• 기획 에이전트

• 개발 에이전트

• 리뷰 에이전트

• 리서치 에이전트

• 테스트 에이전트

하지만 강의에서는 단순히 프롬프트 몇 개로 역할을 나눈 서브에이전트를 진짜 Agent로 보기 어렵다고 설명했습니다.

왜냐하면 그런 에이전트는 대부분 “역할 프롬프트” 수준에 머물기 때문입니다.

반면 목적별 Workspace는 다릅니다.

Workspace 안에는 역할만 있는 것이 아니라, 실제로 Agent가 일할 수 있는 기반이 들어갑니다.

Workspace 안에 들어가는 것

- 이 작업의 목적
- PRD
- CLAUDE.md
- 참고할 지식 문서
- Knowledge Index
- Skills
- 폴더 구조
- 파일 네이밍 규칙
- 출력 형식
- 검증 기준
- Wrap-up 규칙

그래서 Claude Code를 특정 Workspace에서 실행하면,
그 Workspace 자체가 Claude를 특정 역할로 움직이게 만듭니다.

예를 들어 부동산 분석 Workspace가 있다면 이런 구조가 될 수 있습니다.

real-estate-analysis-workspace/
  CLAUDE.md
  00_META/
    analysis-purpose.md
    user-perspective.md
  10_KNOWLEDGE/
    market-patterns.md
    policy-analysis.md
    participant-psychology.md
    index.md
  20_SKILLS/
    real-estate-consil/
      SKILL.md
  30_OUTPUTS/
    reports/

이 Workspace에서 Claude Code를 실행하면, Claude는 단순한 범용 AI가 아니라
“부동산 시장을 특정 기준으로 분석하는 Agent”처럼 작동하게 됩니다.

중요한 것은 이때 Agent의 성격이 Claude 모델 자체에서만 나오는 것이 아니라는 점입니다.

Agent의 성격은 Workspace에 들어 있는 다음 요소들이 함께 만듭니다.

• 어떤 지식을 참고하는가

• 어떤 기준으로 판단하는가

• 어떤 순서로 분석하는가

• 어떤 산출물 형식으로 답하는가

• 어떤 경우에 사용자에게 확인을 요청하는가

• 작업 후 무엇을 업데이트하는가

이 관점이 정말 인상 깊었습니다.

Agent를 많이 만드는 것보다, 목적별 Workspace를 제대로 만드는 것이 더 에이전트답다는 생각이 들었습니다.

5. CLAUDE.md는 긴 프롬프트가 아니라 운영 인덱스다

처음에는 CLAUDE.md를 프로젝트 설명 파일 정도로 생각했습니다.

하지만 강의에서는 CLAUDE.md를 훨씬 더 중요한 문서로 다뤘습니다.

CLAUDE.md는 Claude Code에게
“이 Workspace에서 어떻게 일해야 하는지” 알려주는 운영 인덱스입니다.

조금 더 쉽게 말하면,
Claude Code를 위한 업무 매뉴얼이자 파일 지도입니다.

CLAUDE.md에는 이런 내용이 들어갈 수 있습니다.

# Workspace Identity
- 이 Workspace는 무엇을 위한 작업장인가?
- Claude Code는 여기서 어떤 역할을 해야 하는가?
- 사용자가 중요하게 보는 기준은 무엇인가?

# Source Map
- 먼저 읽어야 할 문서는 무엇인가?
- PRD는 어디에 있는가?
- Knowledge Index는 어디에 있는가?
- 임시 파일이나 참고하지 말아야 할 폴더는 무엇인가?

# Operating Rules
- 작업은 어떤 순서로 진행할 것인가?
- 언제 사용자 확인이 필요한가?
- 어떤 결과물 형식을 따라야 하는가?
- 변경 사항은 어디에 기록해야 하는가?

# Skill Routing
- 어떤 상황에서 어떤 Skill을 사용할 것인가?
- Skill을 쓰기 전 확인해야 할 조건은 무엇인가?
- Skill 실행 후 어떤 검증을 해야 하는가?

# Context & Token Policy
- 긴 입력은 채팅창이 아니라 파일로 받는다.
- 사용하지 않는 MCP와 Skill은 기본 연결하지 않는다.
- 세션이 길어지면 Handoff 문서를 만든다.

# Wrap-up Policy
- 세션 종료 시 변경 사항을 정리한다.
- PRD와 실제 작업 결과가 달라진 부분을 확인한다.
- CLAUDE.md와 Skill 업데이트 후보를 제안한다.

여기서 중요한 점은 CLAUDE.md를 무조건 길게 쓰는 것이 아니라는 점입니다.

길게 설명하는 것보다 더 중요한 것은
Claude가 다음 질문에 답할 수 있도록 만드는 것입니다.

나는 여기서 어떤 역할인가?
먼저 무엇을 읽어야 하는가?
어떤 순서로 일해야 하는가?
어떤 Skill을 써야 하는가?
무엇을 하면 안 되는가?
작업이 끝나면 무엇을 남겨야 하는가?

이 기준이 명확하면 Claude Code는 매번 새로 설명하지 않아도 같은 방향으로 움직일 수 있습니다.

반대로 이 기준이 없으면 매번 대화창에서 다시 설명해야 하고,
세션이 길어질수록 방향이 흔들릴 가능성이 커집니다.

6. Skill은 많이 설치하는 것이 아니라 검증된 절차를 재사용하는 것이다

Skills에 대한 관점도 바뀌었습니다.

처음에는 Skill을 많이 설치하면 Claude Code가 더 많은 일을 할 수 있을 것 같았습니다.

하지만 강의에서는 Skills를 이렇게 봤습니다.

Skill은 검증된 워크플로우를 다시 쓰게 만드는 장치다.

즉, Skill은 “많이 모아두는 기능 목록”이 아닙니다.

반복해서 해봤고,
잘 되는 절차와 실패하는 지점을 확인했고,
다시 써도 괜찮다고 판단한 작업 흐름을 문서화한 것입니다.

Skill을 만드는 흐름은 이렇게 정리할 수 있습니다.

1. 반복되는 작업을 발견한다.
2. Claude Code와 함께 여러 번 실행해본다.
3. 어느 단계에서 잘 되는지 확인한다.
4. 어느 단계에서 자주 실패하는지 확인한다.
5. 성공 조건과 실패 조건을 정리한다.
6. 검증 기준을 추가한다.
7. Skill 문서로 만든다.
8. CLAUDE.md에 언제 이 Skill을 쓸지 연결한다.

예를 들어 “기능 구현 Skill”을 만든다면 단순히
“기능을 구현해줘”가 아닙니다.

이런 식의 절차가 들어가야 합니다.

기능 구현 Skill 예시

입력:
- PRD
- 현재 작업 파일
- 관련 이슈
- 기존 코드 구조

절차:
1. PRD를 읽고 요구사항을 요약한다.
2. 관련 파일을 찾는다.
3. 변경 계획을 먼저 제안한다.
4. 사용자 확인 후 구현한다.
5. 테스트 또는 검증 방법을 실행한다.
6. 변경 사항을 요약한다.
7. 남은 리스크를 정리한다.

검증:
- 요구사항이 빠지지 않았는가?
- 기존 구조를 불필요하게 깨지 않았는가?
- 테스트가 가능한가?
- 문서 업데이트가 필요한가?

이렇게 만들어진 Skill은 Claude Code에게
“이 작업은 이런 순서로 해”라고 알려주는 재사용 가능한 절차가 됩니다.

중요한 것은 Skill을 만들기 전에 먼저 실험하고 검증해야 한다는 점입니다.

검증하지 않은 Skill을 많이 만들어두면 오히려 혼란만 늘어날 수 있습니다.

7. 작업 시작은 PRD부터, 그다음 Workspace다

강의에서 실제 작업 흐름으로 제안한 부분도 좋았습니다.

보통 우리는 Claude Code를 켜고 바로 이렇게 말하기 쉽습니다.

이런 앱 만들어줘.
이 기능 추가해줘.
이 오류 고쳐줘.

하지만 강의에서는 바로 작업하지 말고, 먼저 PRD를 만들고 전용 Workspace를 세팅하라고 했습니다.

흐름은 다음과 같습니다.

하고 싶은 일 정리
→ PRD 작성
→ 전용 Workspace 세팅
→ CLAUDE.md 작성
→ 필요한 Skills 연결
→ Knowledge Index 연결
→ Claude Code 작업 실행
→ Wrap-up
→ PRD / CLAUDE.md / Skill 업데이트

이 방식의 장점은 분명합니다.

작업이 시작되기 전에 목적과 기준이 정리됩니다.

그리고 작업이 끝난 뒤에도 결과가 휘발되지 않습니다.

작업 중 바뀐 결정, 새로 생긴 규칙, 다음에 주의할 점이 다시 Workspace 안에 남습니다.

즉, Workspace가 매번 조금씩 좋아집니다.

이것이 강의에서 말한 업데이트 루프라고 이해했습니다.

작업 실행
→ 결과 확인
→ 달라진 점 정리
→ 운영 문서 업데이트
→ 다음 작업에 반영

이 루프가 없으면 Claude Code는 매번 새로 시작하는 도구에 가깝습니다.

하지만 이 루프가 있으면 Claude Code는 내 작업 방식에 맞춰 점점 더 안정적으로 움직이는 Agent에 가까워집니다.

8. Wrap-up은 예쁜 요약이 아니라 다음 세션을 위한 운영 업데이트다

강의에서 Wrap-up에 대한 설명도 인상 깊었습니다.

보통 작업이 끝나면 Claude에게 요약을 시킵니다.

오늘 한 일 요약해줘.
변경 사항 정리해줘.

그런데 강의에서 말하는 Wrap-up은 단순 요약이 아니었습니다.

Wrap-up은 다음 세션에서 덜 흔들리기 위해 운영 문서를 업데이트할 후보를 뽑는 작업입니다.

예를 들면 이런 질문을 던질 수 있습니다.

이번 작업에서 PRD와 달라진 점은 무엇인가?
CLAUDE.md의 작업 규칙과 실제 작업이 어긋난 부분은 무엇인가?
새로 추가해야 할 금지사항은 무엇인가?
반복되는 절차 중 Skill로 만들 만한 것은 무엇인가?
다음 세션에 반드시 넘겨야 할 내용은 무엇인가?

그래서 Wrap-up 문서는 이렇게 구성할 수 있습니다.

# Session Wrap-up

## 이번 세션에서 한 일
- 

## 바뀐 결정
- 

## PRD와 달라진 점
- 

## CLAUDE.md 업데이트 후보
- 

## Skill 업데이트 후보
- 

## 다음 세션 Handoff
- 

이 구조가 있으면 세션이 끝나도 맥락이 사라지지 않습니다.

다음에 Claude Code를 다시 켰을 때,
이전 작업의 흐름을 훨씬 안정적으로 이어갈 수 있습니다.

9. LLM Wiki와 RAG는 문서를 많이 쌓는다고 해결되지 않는다

강의 후반의 LLM Wiki와 RAG 이야기도 중요한 내용이었습니다.

처음에는 문서를 많이 쌓아두면 AI가 알아서 잘 찾아줄 것이라고 생각하기 쉽습니다.

예를 들어 Obsidian에 문서가 1,000개, 2,000개 있다면
AI가 그중에서 필요한 내용을 찾아 똑똑하게 답해줄 것 같습니다.

하지만 실제로는 문제가 생길 수 있습니다.

• 문서가 많을수록 어떤 문서를 읽어야 할지 찾기 어렵다.

• AI가 의미상 가까운 문서를 정확히 고르지 못할 수 있다.

• 매번 많은 문서를 읽게 하면 토큰이 많이 든다.

• 비슷한 문서가 많으면 검색 품질이 떨어진다.

• 결국 사람이 다시 검증해야 한다.

• AI가 대량 생산한 문서가 오히려 지식 베이스를 오염시킬 수 있다.

그래서 강의에서는 “문서 수를 늘리는 것”보다
“작고 검증된 문서와 인덱스를 만드는 것”을 더 중요하게 봤습니다.

현실적인 구조는 다음과 같습니다.

중요한 문서만 선별한다.
→ 각 문서별 3~5줄 description을 만든다.
→ index.md를 만든다.
→ 질문이 들어오면 index에서 후보 문서를 좁힌다.
→ 필요한 Markdown 문서만 실제로 읽게 한다.
→ 검색이 틀렸던 경우 description과 index를 수정한다.

이 방식은 “모든 문서를 다 읽어”보다 훨씬 안정적입니다.

Claude Code 입장에서도
전체 자료실을 헤매는 것이 아니라,
먼저 도서 목록표를 보고 필요한 책만 꺼내 읽는 방식이 됩니다.

10. 온톨로지나 그래프뷰보다 중요한 것은 사용자의 판단 기준이다

강의에서는 온톨로지와 그래프뷰에 대한 이야기도 나왔습니다.

요즘은 문서들을 그래프로 연결해두면 마치 지식 시스템이 완성된 것처럼 보이기도 합니다.

하지만 강의에서는 단순히 노드와 링크가 있다고 해서 온톨로지가 되는 것은 아니라고 했습니다.

진짜로 의미 있는 지식 구조를 만들려면 이런 기준이 필요합니다.

• 어떤 노드를 만들 것인가

• 어떤 엣지를 연결할 것인가

• 어떤 기준으로 검색할 것인가

• 몇 단계 연결까지 가져올 것인가

• 카테고리별 검색 기준을 어떻게 다르게 둘 것인가

• 새 데이터가 들어왔을 때 어떻게 분류할 것인가

이건 생각보다 어렵습니다.

특히 개인의 모든 지식을 대상으로 범용 세컨드 브레인을 만들려 하면 범위가 너무 넓어집니다.

그래서 강의에서는 거창한 온톨로지를 만들기보다,
작은 지식 베이스와 인덱스를 잘 관리하는 쪽이 더 현실적이라고 했습니다.

또 하나 중요한 점은 사용자의 주관입니다.

AI 시스템을 만들 때 우리는 종종 완전히 객관적인 답을 기대합니다.
하지만 실제로 결과를 검증하는 사람은 결국 사용자입니다.

따라서 Workspace에는 사용자가 중요하게 보는 기준이 들어가야 합니다.

예를 들면 이런 것들입니다.

사용자의 판단 기준

- 어떤 근거를 신뢰하는가
- 어떤 스타일의 결과물을 선호하는가
- 어떤 자동화를 위험하다고 보는가
- 어떤 경우에는 반드시 사용자 확인이 필요한가
- 어떤 문서는 반드시 보존해야 하는가
- 어떤 임시 산출물은 버려도 되는가
- 어떤 기준을 만족해야 결과를 납득할 수 있는가

이 부분이 좋았습니다.

AI에게 주관을 완전히 빼라고 하는 것이 아니라,
오히려 내가 어떤 기준으로 판단하는 사람인지 명시해야 AI도 내 방식에 맞게 움직일 수 있다는 관점입니다.

결과와 배운 점

이번 내용을 정리하면서 가장 크게 배운 점은 이것입니다.

좋은 Agent는 자동화 도구를 많이 붙여서 만드는 것이 아니라, AI가 일할 환경을 제대로 설계할 때 만들어진다.

Claude Code를 잘 쓰는 방법은 단순히 다음과 같은 것이 아니었습니다.

• MCP 많이 설치하기

• Skills 많이 만들기

• 서브에이전트 많이 만들기

• 긴 프롬프트 잘 쓰기

• 자동화 플러그인 붙이기

물론 이런 것들도 필요할 수 있습니다.

하지만 그보다 먼저 필요한 것은 아래 요소들이었습니다.

• 목적이 분명한 Workspace

• 간결하지만 강력한 CLAUDE.md

• 검증된 Skills

• 작은 Knowledge Index

• 토큰과 컨텍스트 관리 기준

• 세션 종료 후 Wrap-up / Handoff

• 사용자의 판단 기준

• 작업 후 운영 문서를 업데이트하는 루프

이번 내용을 제 방식으로 비유하면 이렇습니다.

Workspace = AI가 일하는 책상
CLAUDE.md = 업무 매뉴얼
PRD = 이번에 해야 할 일의 기획서
Skills = 반복 업무 절차서
Knowledge Index = 자료실 목록표
Wrap-up = 퇴근 전 인수인계 문서
Handoff = 다음 근무자를 위한 전달 메모

Claude Code를 그냥 켜고 “알아서 해줘”라고 하는 것은
새 직원에게 아무 책상이나 앉혀놓고 일을 맡기는 것과 비슷합니다.

반대로 Workspace를 잘 세팅하는 것은
새 직원에게 전용 책상, 업무 매뉴얼, 참고 자료, 체크리스트, 보고 양식을 함께 주는 것과 같습니다.

당연히 후자가 더 안정적으로 일할 수 있습니다.

앞으로 적용해보고 싶은 방식

앞으로 큰 작업을 시작할 때는 바로 Claude Code에게 요청하지 않고, 먼저 아래 순서를 적용해보고 싶습니다.

1. 하고 싶은 일을 먼저 정리한다.
2. PRD를 작성한다.
3. 전용 Workspace 폴더를 만든다.
4. CLAUDE.md에 역할과 작업 규칙을 적는다.
5. 참고해야 할 문서를 10_KNOWLEDGE에 넣는다.
6. index.md에 문서별 설명을 작성한다.
7. 반복 작업이 있으면 Skill 후보로 분리한다.
8. Claude Code로 실제 작업을 실행한다.
9. 세션 종료 시 Wrap-up을 만든다.
10. PRD, CLAUDE.md, Skill 업데이트 후보를 반영한다.

예상 Workspace 구조는 이렇게 잡아볼 수 있습니다.

project-workspace/
  CLAUDE.md
  AGENTS.md
  00_META/
    PRD.md
    handoff.md
    session-wrapup.md
  10_KNOWLEDGE/
    index.md
    sources/
    decisions/
  20_SKILLS/
    feature-implementation/
      SKILL.md
      references/
      scripts/
  30_TASKS/
    current.md
    backlog.md
  40_OUTPUTS/
    drafts/
    final/
  .claude/
    commands/
    settings.local.json

그리고 CLAUDE.md는 처음부터 완벽하게 만들기보다, 작게 시작해서 작업 후 계속 업데이트하는 방식이 좋을 것 같습니다.

처음 버전은 이렇게만 잡아도 충분할 것 같습니다.

# Workspace Identity
- 이 Workspace는 무엇을 위한 작업장인가?
- Claude Code는 여기서 어떤 역할을 해야 하는가?

# Source Map
- 먼저 읽을 문서:
  - 00_META/PRD.md
  - 10_KNOWLEDGE/index.md

# Operating Rules
- 작업 전 계획을 먼저 제안한다.
- 큰 변경 전에는 사용자 확인을 받는다.
- 결과물은 40_OUTPUTS에 저장한다.

# Skill Routing
- 기능 구현은 20_SKILLS/feature-implementation/SKILL.md를 따른다.
- 리서치 작업은 20_SKILLS/research-summary/SKILL.md를 따른다.

# Context & Token Policy
- 긴 입력은 파일로 받는다.
- 불필요한 MCP와 Skill은 기본 연결하지 않는다.

# Wrap-up Policy
- 세션 종료 시 session-wrapup.md를 작성한다.
- PRD와 달라진 점을 정리한다.
- CLAUDE.md 업데이트 후보를 제안한다.

바로 해볼 액션 플랜

이번 내용을 보고 바로 해볼 수 있는 일은 크지 않아도 됩니다.

가장 먼저 할 일은 “지금 하고 있는 중요한 작업 하나”를 고르는 것입니다.

그리고 그 작업을 그냥 프로젝트 폴더로 두지 말고,
전용 Workspace로 다시 바라보는 것입니다.

바로 할 일

1. 현재 중요한 Claude Code 작업 하나 고르기
2. 그 작업의 목적을 PRD.md로 작성하기
3. 전용 Workspace 폴더 만들기
4. CLAUDE.md 초안 작성하기
5. 참고 문서가 있다면 index.md 만들기
6. 반복되는 작업 하나를 Skill 후보로 정리하기
7. 작업 후 session-wrapup.md 작성하기

반대로 하지 말아야 할 일도 분명해졌습니다.

하지 말아야 할 일

- 남들이 좋다는 MCP를 한꺼번에 설치하지 않기
- 쓰지도 않는 Skills를 계속 기본 연결해두지 않기
- 긴 지시문을 매번 채팅창에 붙여넣지 않기
- 목적이 다른 Workspace에서 아무 프로젝트나 시작하지 않기
- LLM Wiki를 문서 수 늘리기로 해결하려 하지 않기
- 그래프뷰나 온톨로지라는 말만 보고 시스템이 똑똑해졌다고 착각하지 않기
- 작업 후 Wrap-up 없이 세션을 끝내지 않기

마무리

이번 사례를 통해 느낀 결론은 명확합니다.

Claude Code를 Agent처럼 쓰고 싶다면, 먼저 Agent를 더 많이 만들려고 하기보다
Agent가 일할 Workspace를 제대로 만들어야 합니다.

좋은 Agent는 플러그인 개수에서 나오지 않습니다.

좋은 Agent는 다음 요소들이 함께 맞물릴 때 나옵니다.

• 목적 있는 Workspace

• 명확한 CLAUDE.md

• 검증된 Skills

• 작고 신뢰할 수 있는 Knowledge Index

• 토큰과 컨텍스트 관리

• 작업 후 Wrap-up 루프

• 사용자의 판단 기준

결국 Claude Code를 잘 쓴다는 것은
AI에게 일을 “많이 맡기는 것”이 아니라,
AI가 내 방식대로 일할 수 있는 환경을 만들어주는 일에 가까웠습니다.

이번 정리를 한 문장으로 남기면 이렇게 말할 수 있을 것 같습니다.

좋은 Agent는 플러그인을 많이 붙인 결과가 아니라, 목적 있는 Workspace와 꾸준한 업데이트 루프에서 나온다.