비개발자 직장인을 위한 클로드 코드 입문 — 에이전트 설계서부터 실행·개선까지 5단계

핵심 메시지

• 채팅형 AI가 조언해 주는 친구라면, 클로드 코드는 내 컴퓨터에서 파일을 만들고 고치고 실행까지 하는 팀원에 가깝다.
• 에이전트를 만드는 과정에서 가장 중요한 것은 도구 사용법이 아니라 내 업무를 정확히 언어화한 '에이전트 설계서'다.
• 설계서에는 작업 절차(What), 그 일을 하는 의도(Why), 역할 분담과 사용할 도구(How)를 담아야 한다.
• 판단이 필요한 일은 에이전트에게, 정확하고 반복적인 처리는 코드 스크립트에 맡기도록 영역을 나눠 지정해야 품질이 올라간다.
• 워크플로 중간에 사람이 검토하는 단계를 두면 전부 자동화했을 때보다 오히려 결과물이 좋아진다.

쉽게 이해하기

직장인 대상으로 AI 활용을 다루는 진행자가 코딩을 전혀 모르는 사람의 관점에서 클로드 코드 사용법을 정리했다. 개념부터 명확히 한다. 클로드나 챗GPT 같은 도구는 대화창에서 질문에 답하고 파일을 읽어 주는 데서 멈추지만, 클로드 코드는 내 컴퓨터 안에 들어와 파일을 직접 만들고 수정하고 실행한다. 그래서 조언자가 아니라 실제로 일해 주는 팀원이라는 비유가 나온다. 이렇게 콘텐츠 팀, 전략 기획 팀, 세일즈 팀 같은 가상의 AI 팀을 만들어 운영할 수 있다는 것이다.

설치는 VS 코드라는 코드 편집기 위에서 진행한다. 게임기에 게임 팩을 꽂듯 VS 코드에 클로드 코드를 연결한다는 설명이다. VS 코드를 기본값으로 설치한 뒤 확장 프로그램 메뉴에서 앤트로픽이 만든 공식 확장을 찾아 설치하고 유료 계정으로 로그인하면 준비가 끝난다. 터미널에서 쓰는 방법도 소개되는데, 윈도우에서는 배시를 먼저 깔아야 하고 명령어가 실행되지 않으면 시스템 환경 변수의 경로를 추가하면 된다. 엑셀 처리나 웹사이트 제작에 필요한 엔진 격인 파이썬과 Node.js도 함께 설치해 두기를 권한다.

본론은 나만의 에이전트를 만드는 다섯 단계다. 프로젝트 생성, 에이전트 설계서 작성, 설계 검토, 에이전트 세팅, 실행과 개선 순이다. 프로젝트 폴더는 회사나 팀 단위가 아니라 논문 번역, 유튜브 리서치처럼 작업 단위로 하나씩 만드는 것이 혼선이 적었다고 한다. 진행자는 VS 코드 창을 여러 개 띄워 병렬로 작업한다. 첫 예시는 영문 논문 PDF를 그림과 표, 수식 위치를 그대로 살린 채 한국어 PDF로 바꾸는 작업인데, PDF를 분석하고 이미지를 추출하고 번역해 다시 조합하는 여러 단계의 일은 채팅형 AI로는 어렵다는 점을 보여 주기 위한 선택이다.

가장 강조되는 단계는 두 번째, 에이전트 설계서 작성이다. 좋은 설계도가 있어야 건축물이 잘 지어지는 것과 같다는 비유가 붙는다. 설계서에는 작업의 상세 절차, 그 일을 왜 하는지, 복잡한 작업이라면 에이전트끼리 어떻게 역할을 나눠 협업하고 어떤 도구와 API를 쓸지를 적는다. 여기서 나온 실전 노하우 하나가 에이전트가 처리할 영역과 코드 스크립트가 처리할 영역을 분리해 명시하는 것이다. 그렇게 하지 않으면 클로드 코드가 번역까지 스크립트로 처리하려 들어 품질이 떨어진다. 상황 판단이 필요하거나 비정형 결과물을 만들어야 하는 일은 에이전트 몫으로 지정해 둔다.

세 번째 검토 단계에서는 설계서를 작업 폴더에 넣고 시프트+탭으로 플랜 모드를 켠다. 이 모드에서는 파일을 고치지 않고 읽기만 하며 계획을 세우기 때문에, 본격적으로 코드를 짜기 전에 전체 그림을 먼저 맞출 수 있다. 네 번째 세팅 단계에서 클로드 코드는 폴더 구조와 프로젝트 기본 가이드 문서인 CLAUDE.md, 그리고 스킬과 서브 에이전트를 알아서 만든다. 스킬은 레시피대로 따라 하는 요리, 서브 에이전트는 상황을 보며 자율적으로 판단하는 셰프에 비유된다. 마지막 실행 단계에서는 결과가 아쉬우면 구체적으로 피드백을 주고, 그 내용을 에이전트 파일에도 반영하게 해 다음번에는 같은 문제가 반복되지 않게 한다.

주요 인사이트

• 진행자가 꼽는 성패의 갈림길은 기술이 아니라 메타인지다. 클로드 코드를 잘 쓰는 능력은 코딩 실력이나 도구 이해가 아니라 내 업무를 정확히 파악하고 언어로 전달하는 능력이며, 그 일만큼은 각자가 가장 잘할 수 있다고 말한다.
• 휴먼 인 더 루프를 일부러 넣는다는 점이 인상적이다. 신경을 꺼도 될 만큼 단순한 일이 아니라면 사람이 중간에 검수하거나 추가 입력을 주는 편이 전부 자동화한 것보다 품질이 높고, 그 유연함 때문에 노코드 자동화 도구보다 업무 활용에 유리하다고 본다.
• 블로그 사례에서 나온 수치가 구체적이다. 팀을 축소해 마케팅 담당자가 없어지자 월 1만 명이던 방문자가 4천 명대까지 떨어졌는데, 직접 만든 에이전트로 다시 글을 발행하며 회복했다고 밝힌다.
• 에이전트가 인터넷에서 알아서 리서치하게 하면 인사이트가 흐릿해진다는 관찰도 나온다. 대신 사람이 양질의 유튜브 영상을 골라 입력으로 넣는 방식으로 개입 지점을 만들었고, 그 선별 과정이 결과물의 질을 끌어올렸다고 설명한다.
• 컨텍스트가 쌓이면 에이전트가 둔해진다는 이유로, 설계서 작성이 끝나면 대화를 비우고 새 창에서 다음 단계를 진행하기를 권한다. 프롬프트와 코드를 사람이 한 줄씩 검토하기보다 실제로 돌려 보며 고치는 편이 효과적이라는 조언도 함께 나온다.

자주 묻는 질문

관련 AI 소식