AI 에이전트로 웹스튜디오 사이트를 만든 8가지 스킬

4일이 채 안 되는 기간 동안 340개의 커밋, AI “직원” 7명과 인간 1명. 가장 중요했던 기술은 에이전트가 멈추게 만드는 기술이었다.

나는 Sorrei Studio라는 작은 웹 스튜디오를 운영한다. 첫 번째 프로젝트는 스튜디오 자신의 웹사이트다. 지역 비즈니스 3종, 즉 카페, 농가 숙박, 재봉용품점을 위한 개념 데모 사이트가 포함된 이중 언어 포트폴리오다. 이 작업에 참여하는 사람은 나를 제외하면 모두 AI 에이전트다.

10월 11일 저녁의 첫 커밋부터 10월 15일 새벽 사이에, 저장소에는 340개의 커밋이 쌓였다. 3개의 데모 중 2개는 코드 리뷰, QA, 보안 점검을 거쳐 병합되었다. 이 프로젝트에는 50개의 단위 테스트 파일과 14개의 엔드투엔드 스펙이 있으며, 이들은 세 가지 화면 너비에서 Chromium으로 실행되고, 여기에 WebKit과 Firefox용 크로스 브라우저 스위트도 더해진다.

아직 아무것도 라이브 상태는 아니다.

이건 고백이 아니다. 이 글의 요점이다. “AI가 처음부터 프로덕션까지 스스로 소프트웨어를 만든다”는 멋진 헤드라인이 되지만, 실제로 에이전트에게 가장 유용했던 습관은 어떤 결정은 자기 몫이 아니라는 걸 아는 것이었다. 내가 여기까지 올 수 있었던 건 더 똑똑한 모델 덕분이 아니었다. 에이전트 스킬 덕분이었다. 작업이 필요로 할 때 에이전트가 불러오는 짧은 문서화된 절차들이다.

다음은 내가 의존하는 8가지 스킬이다. 프로젝트가 처음 만나는 순서대로, 그리고 각각 실제로 일어났던 일 하나씩과 함께 소개한다.

먼저, Agent Skill이란 무엇인가?

스킬은 그 안에 SKILL.md 파일이 들어 있는 폴더다. 이 파일은 짧은 YAML 헤더(name과 description)로 시작하고, 그 뒤에 자연어 지침이 이어진다. 폴더에는 스크립트와 참고 파일도 함께 둘 수 있다.

핵심은 로딩 방식이다. 시작 시 에이전트는 각 스킬의 이름과 설명만 본다. 어떤 작업이 설명과 맞아떨어지면, 에이전트는 전체 지침을 읽는다. 이렇게 하면 수십 개의 스킬을 설치해 두어도 컨텍스트 창을 채우지 않을 수 있다.

Anthropic은 2025년 10월 이 형식을 소개했고, 같은 해 12월 agentskills.io에서 오픈 표준으로 공개했다. Claude Code, OpenAI의 Codex, Gemini CLI, GitHub Copilot, Cursor, 그리고 그 밖의 긴 도구 목록이 이제 같은 형식을 읽는다.

아래의 스킬들 대부분은 Jesse Vincent(GitHub에서는 obra)의 오픈소스 스킬 라이브러리인 Superpowers에서 가져왔다. 나머지는 내가 직접 만들었다.

한 문단으로 보는 설정

메인 세션의 Claude는 프로젝트 매니저처럼 행동한다. 계획을 세우고, 업무를 위임하고, 검토하고, 나에게 보고한다. 7명의 서브에이전트가 일을 맡는다: 리서처, 디자이너, 작가, 개발자, 리뷰어, QA, 보안 담당. 각각은 역할과 허용된 도구 목록이 적힌 Markdown 파일이며, 오직 PM에게만 보고하고 나에게는 직접 보고하지 않는다. PM은 기술적 세부 사항을 스스로 정리하고, 내 대신 내린 모든 판단은 “만약 이게 틀렸다면”이라는 열이 있는 로그에 기록되므로, 나는 언제든지 되돌릴 수 있다. 시각적인 것, 가격이 걸린 것, 공개되는 것, 그리고 모든 push나 deploy는 나에게 온다. 내 결정도 날짜와 함께 기록된다.

1. brainstorming: 만들기 전에 먼저 대화하기

단계: 아이디어에서 승인된 디자인까지.

이 스킬은 에이전트가 요청을 듣자마자 코드를 쓰지 못하게 막는다. 한 번에 한 질문씩, 그게 무엇을 위한 것인지 묻는다. 그런 다음 작업을 빠른 스파이크인지, 범위가 정해진 변경인지, 아니면 아키텍처 작업인지로 분류하고, 명시적인 승인이 없으면 다음 단계로 넘어가지 않는다.

또한 에이전트에게 반박할 권한도 준다. 첫날 나는 랜딩 페이지에 첫 단계부터 CMS를 넣고 싶었다. PM은 반대했고, 결국 2단계에서 커스텀 관리 패널을 만들기로 합의했으며, 카페 데모의 메뉴부터 시작했다. 내 결정 로그에는 내가 PM과 디자이너를 번복한 사례도 기록되어 있다. 둘 다 로고에 더 개성 있는 서체를 추천했지만, 나는 원래 고른 글꼴을 유지했다.

2. writing-plans: 검토할 수 있을 만큼 작은 작업들

단계: 디자인에서 계획으로.

여기서 계획은 번호가 매겨진 작업들의 파일이다. 각 작업에는 건드릴 파일, 작성할 테스트, 그리고 “완료”의 의미가 적혀 있다. 저장소에 있는 4개의 계획에는 합쳐서 40개의 작업이 들어 있고, 농가 숙박 데모에는 10개가 있었다.

크기를 일부러 작게 잡는다. 한 작업은 한 에이전트가 끝낼 수 있고, 한 리뷰어가 한 번에 읽을 수 있어야 한다. 계획이 “예약 페이지를 만든다”고만 말하면, 품질은 운에 달린다. 반면 “이 props와 이 테스트를 포함한 날짜 범위 달력을 추가하되, 테스트는 반드시 먼저 실패해야 한다”고 적혀 있으면, 에이전트가 자신의 결과를 확인할 기준을 갖게 된다.

3. subagent-driven-development: 작업마다 새 에이전트 하나씩

단계: 빌드.

한 번의 긴 세션이 모든 결정을 머릿속에 담고 가는 대신, PM은 각 작업마다 그 작업에 필요한 것만 가진 새 서브에이전트를 투입합니다. 완료된 각 작업은 다음 작업이 시작되기 전에 검토됩니다.

새로운 컨텍스트의 가치는 제가 예상했던 것보다 더 컸습니다. 긴 세션은 이전의 추론을 스스로 믿기 시작하지만, 새 에이전트는 코드를 있는 그대로 읽습니다.

또한 작업에 맞는 모델을 고를 수 있게 해 줍니다. 저장소의 모든 커밋에는 그 커밋을 만든 모델이 적혀 있습니다. 241개는 Opus, 92개는 Sonnet, 7개는 Haiku가 만들었습니다. 잘 명세된 작업은 가장 큰 모델이 꼭 필요하지 않은 경우가 많습니다.

4. 테스트 주도 개발: 테스트가 먼저 실패하는지 확인하기

단계: 빌드 중.

규칙은 오래되었습니다. 테스트를 작성하고, 실행해서 실패하는 것을 본 뒤, 코드를 작성합니다. 에이전트에서는 이 규칙이 더 중요합니다. 방금 코드를 작성한 에이전트가 그 코드를 테스트하면, 실패할 수 없는 테스트를 태연하게 만들어 버릴 수 있기 때문입니다.

우리도 그랬습니다. PM이 “콘텐츠로 건너뛰기” 링크용 테스트를 처음 작성했을 때, 링크가 동작하든 말든 통과했습니다. PM 자신의 로그에도 그것이 실수였다고 기록되어 있습니다. 그 이후로 우리 품질 기준은 분명히 이렇게 말합니다. 모든 테스트는 로직이 잘못되었을 때 실패할 수 있어야 하며, TDD에서는 먼저 그 실패를 확인해야 합니다. WhatsApp 메시지 빌더에 잘못된 문자(이모지의 서로게이트 페어 절반)를 검사하는 테스트를 추가했을 때도, 버그를 잡아낼 수 있음을 증명하기 위해 먼저 수정 전 코드에 대해 실행했습니다.

5. 새로운 시각으로 코드 리뷰하기

단계: main에 도달하기 전.

Superpowers에는 코드 리뷰를 요청하고 받는 스킬이 있습니다. 우리의 리뷰어 에이전트는 해당 작업의 커밋, 계획, 프로젝트 규칙만 봅니다. APPROVED 없이는 어떤 것도 main에 들어가지 않으며, "문제 없음" 보고서에는 무엇을 점검했는지 적어야 합니다.

제가 계속 기억하는 두 가지 실수가 있습니다. 장바구니를 만들기 전에, 리뷰에서 계획이 브라우저의 localStorage에서 읽어온 항목 가격을 신뢰할 것이라고 지적했습니다. 그런데 이는 어떤 방문자든 수정할 수 있는 값입니다. 지금 장바구니는 항목 ID와 수량만 저장하고, 불러올 때마다 카탈로그에서 이름과 가격을 다시 구성합니다. 또한 엔드투엔드 테스트가 저장소를 조작해 이를 증명합니다.

두 번째는 예약 페이지를 리뷰할 때 나왔습니다. 우리 기계는 비즈니스와 같은 자카르타 시간으로 동작하므로, 시간대 버그는 테스트에서 절대 드러나지 않았을 것입니다. 이제 전체 명세는 America/Los_Angeles에서 실행되어, 모든 테스트가 변환을 검사합니다.

340개 커밋 중 89개가 fix:로 시작합니다. 저는 이것을 리뷰 루프가 제대로 작동하고 있다는 뜻으로 읽습니다.

6. 완료 전 검증: 증거가 없으면 없었던 것이다

단계: 누구도 “완료”라고 말하기 전.

스킬을 하나만 설치한다면 이걸 고르세요. 에이전트가 명령을 실행하고 출력 결과를 먼저 보여 주지 않고는 “테스트가 통과했습니다” 또는 “반응성이 좋습니다”라고 말하지 못하게 막습니다. 에이전트는 자신감 넘치는 서술자이기 때문에, 이 한 가지 규칙이 거짓 보고의 큰 범주를 없애 줍니다.

우리 버전은 더 나아갑니다. QA는 모든 페이지를 가로 360, 768, 1280픽셀로 스크린샷 찍고 각 이미지를 열어 확인합니다. 나중에는 WebKit과 Firefox에서 일회성 스모크 테스트를 승인했고, Chromium에서는 드러나지 않던 버그 세 개를 찾아냈습니다. Safari에서는 실패한 제출 뒤 빈 필수 입력란이 화면으로 스크롤되지 않았습니다. Firefox에서는 예약이 꽉 찬 날짜의 해치 패턴이 잘못 그려졌습니다. 그리고 Safari는 대화상자 제목에 포커스 링을 표시했습니다. 세 가지 모두 수정되었고, 두 개의 영구적인 크로스브라우저 테스트 프로젝트가 이를 계속 고정해 둡니다.

7. 체계적 디버깅: 수정하기 전에 원인을 찾기

단계: 무언가가 깨졌을 때.

규칙은 간단합니다. 근본 원인을 설명할 수 있을 때까지는 수정하지 마세요. 에이전트는 증상만 땜질하는 것을 좋아합니다. !important를 추가하고, 타임아웃을 늘리고, try/catch로 감싸 버립니다.

Firefox의 해치 패턴이 좋은 예입니다. 정교한 7픽셀 크로스해치 대신, Firefox는 몇 개의 거대한 대각선 줄무늬를 그렸습니다. 급한 패치는 Firefox 전용 오버라이드였을 것입니다. 진짜 원인은 선 색상이었습니다. 그 색은 color-mix()에서 왔는데, 이는 color(srgb …) 값으로 해석되며, Firefox는 이를 repeating-linear-gradient 안에서 제대로 그리지 못합니다. 해결책은 같은 테마 토큰의 30% 불투명도에 해당하는 단순한 rgb() 색을 쓰는 것이었고, 두 값이 서로 어긋나지 않도록 하는 단위 테스트도 추가했습니다.

8. 모든 데모의 끝과 모든 배포 전의 보안 점검

단계: 머지 전과 릴리스 전.

이건 제가 직접 만들었습니다. 보안 에이전트가 실제 명령으로 실행하는 체크리스트입니다. 코드와 git 히스토리에서 비밀 정보를 검색하고, 의존성을 감사하며, 보안 헤더와 CSP를 확인하고, XSS 싱크와 안전하지 않은 링크를 찾고, 장바구니 외에는 아무것도 localStorage에 들어가지 않는지 확인합니다. 결과는 CLEAR 또는 BLOCKED입니다.

각 데모는 실제 비즈니스의 이름을 사용하는 비공개 버전을 가질 수 있으며, 이는 오직 소유자만을 위한 것으로 추측 불가능한 링크를 통해서만 접근할 수 있습니다. 첫 번째 설계에서는 모든 데모에 하나의 토큰을 사용했습니다. 보안 검토에서 이를 문제로 지적했습니다. 한 번 유출된 링크 하나로 모든 비즈니스의 비공개 페이지가 열릴 수 있었기 때문입니다. 이제 각 비즈니스는 고유한 토큰을 가지며, 두 토큰이 같거나 하나가 다른 하나를 포함하면 빌드가 실패하고, 한 비즈니스의 링크로 다른 비즈니스의 페이지를 열 수 없다는 테스트도 통과합니다.

보너스: 직접 만든 스킬 작성하기

이 스튜디오에 특화된 네 가지 스킬은 두 번씩 발생한 실수에서 나왔습니다.

• build-demo는 새 데모를 위한 파이프라인입니다. 리서치, 브리프, 시각적 방향에 대한 제 승인, 계획, 빌드와 리뷰 루프, QA, 보안, 다른 데모들과의 나란히 비교하는 “맛보기 점검”, 그리고 보고서로 이어집니다. 빨간 신호 섹션에는 “방향이 너무 뻔하니 오너 게이트를 건너뛰자”처럼 멈춰야 한다는 뜻의 생각들이 적혀 있습니다.
• quality-check는 각 항목이 명령 출력, 스크린샷 경로, 또는 명시적인 SKIP과 그 이유로 끝나는 체크리스트입니다. QA의 첫 실제 실행에서 드러난 빈틈 때문에 다시 작성되었습니다.
• write-content는 사이트 문구의 어조를 정하고, 흔한 AI 용어인 금지된 문구 목록을 가리킵니다. 이 글은 그 기준에 맞춰 검토되었습니다.

이것들을 작성하면서 얻은 한 가지 교훈은 설명이 트리거라는 점입니다. PM의 첫 초안은 각 스킬이 무엇인지 설명했습니다. 그 초안은 자기 자신의 실수를 발견했고, 네 개 모두를 “Use when…”으로 다시 써서 그 스킬을 불러야 하는 상황을 뒤에 붙였습니다. 설명이 에이전트가 작업을 매칭하는 기준이기 때문입니다.

---name: build-demodescription: Use when starting a new concept demo website for a business.---

# Build a demo## Pipeline (gates cannot be skipped or reordered)1. Research check ...2. Brief ...3. GATE: the owner approves the visual direction.   Don't build until there is an explicit yes....## Red flags: stop if you think- "The direction is obvious, skip the owner gate." Gate 3 is mandatory.- "Tests pass, so it's done." Done also needs QA screenshots and the taste check.

아무도 배포하지 않는 스킬: 언제 멈춰야 하는지 아는 것

그렇다면 왜 사이트는 아직 라이브가 아닐까요?

남은 일은 에이전트가 혼자 결정할 수 있는 범위를 벗어나 있기 때문입니다. 스튜디오의 자체 랜딩 페이지는 아직 일정에 남아 있습니다. 호스팅과 실제 도메인을 정해야 하고, 소셜 미디어의 링크 미리보기도 그 도메인을 필요로 합니다. 그리고 굳이 설명하기보다 직접 고치고 싶은 보안 항목이 하나 있습니다. 마지막으로 제 승인도 남아 있습니다. 규칙상 에이전트는 제 승인 없이 절대 push하거나 deploy하지 않으며, 지금까지도 그렇습니다.

그게 “AI가 처음부터 운영 단계까지 소프트웨어를 혼자 만들 수 있나?”라는 질문에 대한 솔직한 답입니다. 대체로 그렇습니다. 빈 저장소에서 시작해 검토되고, 테스트되고, 병합된 코드까지는 가능합니다. 하지만 저장소 밖에 영향을 미치는 결정, 즉 브랜드가 어떻게 보일지, 고객이 얼마를 지불할지, 무엇을 공개할지는 책임질 수 없습니다. 이 작업을 가능하게 만든 스킬들은 에이전트를 더 빠르게 만든 것들이 아니었습니다. 멈추고, 증거를 보여 주고, 묻게 만든 것들이었습니다.

어디서 시작할까

이번 주에 세 가지를 설정한다면:

1. 완료 전에 검증하기. 비용은 들지 않고, 가장 많은 가짜 “완료”를 잡아냅니다.
2. 각 작업마다 새로운 맥락을 가진 리뷰어 한 명. 그 사람은 diff와 규칙은 보지만, 작성자의 사고 과정은 보지 않습니다.
3. 자신만의 스킬 하나. 에이전트에게 같은 점을 두 번째로 바로잡게 되었을 때 작성한 것.

그다음 어떤 결정은 어디까지나 내 몫인지 적어 두세요. 그 목록은 어떤 에이전트도 대신 써 줄 수 없는 설정의 일부입니다.

Reichan Muhammad Maulana는 인도네시아 반둥 근처에서 작은 웹 스튜디오 Sorrei Studio를 운영합니다.

출처

• 원문: https://medium.com/@reichan.muhammad/zero-to-almost-production-8-agent-skills-behind-my-all-ai-web-studio-55ffc691fec6?source=rss------claude_code-5 (2026-10-14 · Reichan Muhammad)