AI 코딩 에이전트에게 같은 지적을 여러 번 하고 계시지는 않습니까?

"날짜는 dayjs를 사용하라고 했는데", "그 버튼, 또 이중으로 전송할 수 있어", "그 색상, 토큰에 있는데 하드코딩했네". 모델은 똑똑한데도 불구하고, 당신의 팀이 과거에 저질렀던 실패를 알지 못합니다. 그래서 같은 실수를 반복하게 됩니다.

저자 팀에서는 AI 리뷰의 지적 중 '과거에 나왔던 것과 동종의 지적'을 예방 가능 위반(preventable violation)이라 부르며 매 태스크마다 계산하고 있습니다. 최근 몇 개 태스크를 측정해 본 결과, 이것이 최초 지적의 약 4할 (22/53건)을 차지했습니다. 이들은 리뷰와 수정의 루프가 감지하여 자동으로 고칠 수 있는 것들입니다. 하지만 이미 알려진 실수라면, 탐지해서 고치는 것보다 애초에 나오기 전에 없애고 싶습니다. 탐지 → 수정의 왕복에는 매번 비용이 들기 때문입니다.

그래서 발상을 바꿨습니다. 모델이 똑똑해지는 것을 기다리는 것이 아니라, 환경 자체가 학습하도록 만드는 것입니다. 본 시리즈는 실제 운영 중인 Claude Code Skills 그룹(스킬 18개, 서브 에이전트 12체)을 소재로, 그 제작 과정을 총 4회에 걸쳐 소개합니다.

전체 개요 (본 기사) — 4가지 '〇〇 엔지니어링'의 흐름과 환경 전체 설계 - 설계서 한 장에서 구현/리뷰/PR까지 — 개발 플로우를 돌리는 오케스트레이터 Skill

• AI 리뷰 지적을 자산화하기 (작성 중) — 추가 전용 로그와 예방 DoD로 만드는 자기 학습 루프
• Figma to Code를 폐쇄 루프로 만들기 (작성 중) — 측정 우선의 시각 일치 루프

1. 4가지 '〇〇 엔지니어링' — 프롬프트 너머에 무엇이 있는가

먼저, 본 시리즈의 위치를 정리하겠습니다. AI 코딩 설계 기법은 이 몇 년 동안 단계적으로 쌓여왔습니다.

참고로, 이 계층 구분은 논자마다 다릅니다. Loop Engineering을 명명한 Addy Osmani 자신도 Loop를 'Harness보다 한 단계 위'로 위치시키면서도, 두 가지를 '사촌(cousin)'이라고 부르기도 합니다[1]. Harness 쪽에 피드백 루프까지 포함하는 넓은 정리도 존재하며, 경계선이 확정된 것은 아닙니다. 본 기사의 4개 계층은 '관심사가 1회의 응답 내용에서, 계속 돌아가는 시스템으로 바깥쪽으로 확장되어 가는' 순서를 보여주는 개요도로 사용합니다.

Harness Engineering을 정착시킨 Mitchell Hashimoto는 그 정의를 이렇게 쓰고 있습니다[2].

에이전트가 실수할 때마다, 같은 실수가 일어나지 않도록 환경 쪽에 영구적인 수정을 가하는 것.

다만, 이 '영구적인 수정'을 사람의 마음가짐에 맡겨두면, 바쁜 주부터는 지켜지지 않게 됩니다. 본 시리즈에서 소개하는 것은, 이것을 데이터 구조와 정형 플로우로 구현하여 잊을 수 없게 만든 실제 사례입니다. 새로운 개념의 발명이 아니라, 이 흐름 위에 있는 실천 보고서로 읽어주시면 좋겠습니다.

2. 전제: 어떤 환경으로 운영하고 있는가

저자 팀에서는 관리 화면 및 사용자용 프론트엔드 2개(Next.js), 백엔드 API(NestJS), Playwright E2E를 포함하는 모노레포를 운영하고 있으며,

.claude/skills

에 18개의 스킬, .claude/agents

에 12개의 서브 에이전트 정의를 두고 있습니다.

.claude/ 디렉터리의 전체 개요는 다음과 같습니다.

.claude/
├── skills/ # 18 스킬
│ ├── workspace-plan/ # ★개발 플로우 전체의 오케스트레이터(제2회 주인공)
...

3. 기반 설계: '상시 로드'와 '가져오는 지식'을 분리하기

루프 이야기에 들어가기 전에, 기반이 되는 정보 설계(Context 계층)를 다룹니다. 여기가 부실하면 위에 무엇을 쌓아도 무너집니다.

분류 기준은 한 줄

Claude의 컨텍스트는 유한합니다. 그래서 규칙을 물리적으로 2가지로 분리했습니다. 판단 기준은 이 한 줄뿐입니다.

'이 규칙을 모르는 상태에서 코드를 작성하면 곤란할까?'

• 곤란하다 → CLAUDE.md

(상시 로드) - 곤란하지 않다 (태스크 발생 시 가져오면 된다) → Skill

"날짜 생성은 new Date() 금지, 반드시 dayjs 사용", "any 금지"와 같이, 모르는 상태에서 작성하면 매번 수정해야 하는 규칙은 CLAUDE.md에 작성합니다. 반면 "메일 템플릿 추가 절차"와 같이 그 시점에 처음으로 필요한 지식은 Skill로 분리합니다.

실제 CLAUDE.md는 예를 들어 다음과 같은 수준으로 작성되어 있습니다 (발췌 및 마스킹 완료).

- any 타입은 가급적 사용하지 말고, 최대한 명확한 타입을 사용해 주세요
- **날짜 생성에는 new Date() 대신 반드시 dayJs를 사용해 주세요**
- 백엔드: `import { dayJs } from 'src/utils/dayJs'`
...

사소해 보이지만, import 경로와 실제 사례까지 작성하는 것이 포인트입니다 (dayJs는 날짜 라이브러리 dayjs를 팀 설정에 맞춰 래핑(wrap)한 자체 제작 유틸리티입니다). "날짜 라이브러리를 사용할 것"이라고만 적으면, 에이전트는 매번 조금씩 다른 방식으로 코드를 작성합니다.

Skill은 「목차 + 실체」의 4층 구조

각 Skill 또한 모든 내용을 한꺼번에 읽게 하지 않는 구조로 설계했습니다.

• SKILL.md는 "어떤 태스크일 때 어떤 파일을 열 것인가"를 결정하는 라우팅(routing) 표 역할에 집중합니다 (기준 30~50행. 오케스트레이터(orchestrator)와 같은 큰 스킬이라도 100행 이내로 유지하고, 상세 내용은 하위 계층으로 넘깁니다).
• **operations/**는 그대로 위에서부터 실행할 수 있는 번호가 매겨진 대본입니다.
• **reference/**는 준수해야 할 규약과 과거에 겪었던 시행착오(지뢰)입니다. 추상론이 아니라 NG/OK 사례가 포함된 실제 코드를 바탕으로 작성합니다.
• **examples/**는 완결된 동작 가능한 샘플입니다.

상시 로드되는 것은 frontmatter의 description뿐입니다. 여기에 서브 작업(sub-operation)의 키워드를 과부족 없이 나열해 두면, Claude가 태스크에 따라 해당 Skill을 자동으로 찾아가며, SKILL.md를 읽고 필요한 파일만 엽니다. "필요할 때만 읽어오는" 목차 메커니즘(지연 로딩, lazy loading)을 직접 구현하고 있는 셈입니다.

---
name: workspace-plan
description: 플래닝용 워크스페이스 초기화 및 관리 + 개발 플로우 전체
...

「유일한 정답」 원칙과 스킬 자체의 lint

스킬이 십수 개 규모로 늘어나면서 효과를 보고 있는 운영 규칙이 두 가지 있습니다.

유일한 정답 (single source of truth): 동일한 정보를 두 개의 파일에 쓰지 않습니다. 정보를 쓰고 싶다면 한쪽을 참조 링크로 만듭니다. 예를 들어, 각 서브 에이전트가 사용하는 모델명은 agent 정의의 frontmatter에만 작성하고, 스킬 측에는 작성하지 않습니다. 중복해서 작성된 정보는 반드시 한쪽만 업데이트되어 모순(drift)이 발생하게 됩니다.

스킬 자체를 lint 하기: 필수 섹션의 누락, 포트(port) 정의의 불일치, 집계되지 않은 로그의 행 수 등, 스킬 구성의 건전성을 검사하는 스크립트를 준비하여 스킬이나 agent 정의를 편집할 때마다 반드시 실행합니다. 스킬 군(group) 또한 훌륭한 "코드"입니다. 코드와 마찬가지로, 망가졌음을 인지할 수 있는 장치를 마련해 둡니다.

4. 자기 학습형 개발 환경의 전체상 — 3가지 루프

이 토대 위에 3가지 루프가 올라가 있습니다. 여기서부터가 본 시리즈의 본체입니다. 다만 본 기사에서는 전체적인 조감도를 그리는 단계이며, 상세 내용은 각 회차로 넘기겠습니다.

(색상 구분: 파랑=플로우 공정 / 청록=서브 에이전트 작업 / 보라=학습 계열 메커니즘)

루프 1: 개발 플로우의 루프 (제2회). 설계서 1장을 입력값으로 하여, 구현 → 6가지 관점 리뷰 (BE 3관점 + FE 3관점, 총 6체) → 수정 → 테스트 → 최종 게이트 → PR 과정을 메인 세션(지휘자)이 서브 에이전트에게 맡기며 순환합니다. 메인은 구현 코드를 직접 작성하지 않습니다. 인간이 등장하는 것은 5개의 확인 게이트뿐입니다. 루프에는 "멈추는 방법"("수정은 3회차까지만", "진전이 없거나 제자리걸음인 경우 감지", "인간에게 인계")까지 정의되어 있습니다.

루프 2: 환경의 자기 학습 루프 (제3회 · 집필 중). 태스크 완료 시마다 진행하는 회고 (retrospective)를 통해, 리뷰 지적 사항을 추가 전용 로그 (1지적=1행. 병렬 브랜치를 머지해도 카운트가 사라지지 않는 설계)에 쌓아 나갑니다. 로그가 일정량을 초과하면 다시 집계하여, 각 리뷰 에이전트의 빈출 위반 랭킹을 업데이트합니다. 다음 리뷰에서는 자주 발생하는 실수부터 중점적으로 체크합니다. 구현 전에 방지할 수 있었던 지적 사항은 예방 DoD (제출 전 셀프 체크리스트)에 다시 기록하여, 구현 에이전트가 제출 전에 스스로 체크하도록 합니다. 서두에서 언급한 "AI가 같은 실수를 두 번 다시 하지 않는다"의 실체가 바로 이 루프입니다.

루프 3: 시각 일치 루프 (제4회 · 집필 중). Figma → 구현 → Storybook 촬영 → 픽셀 단위 측정 (화소 측정)에 의한 비교 → 수정을 차분이 제로가 될 때까지 반복합니다. "육안으로 대충 맞다"라고 보고하는 것을 금지하며, 판정에는 실제로 측정한 수치 (px / 컬러 코드)를 요구합니다. 그리고 여기에도 "실패 빈도 랭킹"이라는 학습 메커니즘이 포함되어 있어, 과거에 외관상 실수가 많았던 항목일수록 더 세밀하게 측정됩니다.

3가지 루프는 대상은 다르지만, "닫기 · 측정하기 · 배움을 다시 쓰기"라는 세 가지 점에서 동일한 형태를 띠고 있습니다.

또한 "효과가 있는가"는 감각이 아니라 메트릭스 (metrics)로 확인합니다. 태스크마다 첫 번째 리뷰의 P0/P1 지적 수 (P0=반드시 수정 / P1=수정해야 함, 의 중요도 라벨) · 예방 가능한 위반 수 (기존 실수의 재발 수) · 수정 반복 횟수 등을 정해진 형식의 한 줄로 기록하여, grep으로 집계할 수 있도록 해두었습니다. 숫자의 상세 내용은 제3회 (집필 중)에서 다룹니다.

5. 요약 — "Skills를 쓰는 것"에서 "Skills가 자라나는 구조를 쓰는 것"으로

환경이 학습한다는 것은 거창한 ML (머신러닝) 이야기가 아닙니다. 실수의 기록 장소를 정하고, 반영 타이밍을 플로우 (flow)에 고정하며, 효과를 하나의 숫자로 측정하는 것. 그뿐인 일을 인력의 마음가짐이 아니라 구조로 만드는 것을 의미합니다.

도입 체크리스트를 남겨둡니다.

• CLAUDE.md와 Skill을 "모르고 작성되면 곤란한가?"를 기준으로 분류했는가
• Skill은 목차 (SKILL.md) + 실체 (operations / reference)의 지연 로딩 (lazy load) 구조인가
• 동일한 규칙을 두 곳에 작성하지 않았는가 (유일한 정답)
• 에이전트의 실수를 "환경 측으로의 영구적 수정"으로 변환하는 장소 (로그 · DoD)가 있는가
• 그 효과를 측정하는 숫자 (메트릭스)를 하나라도 취하고 있는가

프롬프트를 연마하는 시대에서 컨텍스트 (context)를 설계하는 시대로. 그리고 지금, 발판을 짜고 그 발판이 스스로 움직이며 자라나는 루프를 설계하는 시대에 들어서고 있습니다. "Skills를 쓰는 것"에서 멈추지 않고, "Skills가 자라나는 구조를 쓰는 것"까지 나아가는 것 — 그것이 루프 엔지니어링 (Loop Engineering)의 입구라고 생각합니다.

다음 회차에서는 개발 플로우 전체를 돌리는 오케스트레이터 (orchestrator) Skill의 구현을 자세히 살펴보겠습니다.

참고 링크

• Loop Engineering 입문: AI 코딩 에이전트를 구동하는 시스템을 설계하다 (suwash)

• Loop Engineering (루프 엔지니어링)이란 (Qiita, y-morimatsu)

• Claude Code로 하네스 엔지니어링 (harness engineering)을 실천하기 — 5층 설계 패턴 (sasadango28)

• Claude Code로 하네스 엔지니어링을 실천하기 ~사냥에서 농사로 (ignission)

• 컨텍스트 엔지니어링 입문 (shunsuke_stack)

• Claude Code Skill 만드는 법 | 21개를 운용하며 알게 된 설계와 육성법 (yamato_snow)

Addy Osmani의 "Loop Engineering"로부터. "Loop engineering sits one floor above the harness." / "the cousin of this, agent harness engineering" (https://addyo.substack.com/p/loop-engineering) ↩︎

Mitchell Hashimoto의 「My AI Adoption Journey」(2026년 2월) 중 일부를 번역함. 원문: "It is the idea that anytime you find an agent makes a mistake, you take the time to engineer a solution such that the agent never makes that mistake again." (https://mitchellh.com/writing/my-ai-adoption-journey). 참고로 본인은 "업계에 정착된 용어가 있는지는 모르겠지만, 나는 이렇게 부른다"라는 단서를 달고 명명했습니다. ↩︎

Discussion