Series · 연재총 23편
Agent SDD 개발 일지
AI 코딩 에이전트를 회사 일과 개인 프로젝트에 붙이면서 남긴 기록입니다. 처음에는 절차를 하나씩 더해 가며 Agent를 붙잡았고, 모델이 좋아진 뒤에는 그 절차가 아직 필요한지 다시 재고 있습니다. 모델 바깥에서 Agent를 붙잡는 이런 절차와 검사, 규칙을 요즘은 하네스(harness)라고 부르는데, 이 연재는 그 하네스를 직접 만들고 다시 재 본 기록이기도 합니다. 처음이라면 1편부터, 최근 이야기는 12편부터 읽으면 됩니다. 글에 나오는 이름이 헷갈리면 아래 자주 나오는 이름을 먼저 보세요.
시리즈에서 사용한 규칙과 Skill은 agent-sdd-kit으로, 워크플로 전체는 adaptive-agentic-sdd로 공개했습니다.
기초
1~4편작업을 위험도로 나누고, 명세를 먼저 쓰고, 백로그로 세션을 잇고, 끝난 문서를 정리하는 기본 흐름.
01
AI한테 일을 시킬 때, 다 똑같이 다루면 안 되더라2026.06.25
규모·리스크로 작업을 다섯 등급으로 나눠 프로세스의 무게를 조절하다.
02
Agent에게 바로 개발시키지 않기2026.06.25
명세·영향분석·검증 기준을 단계별 산출물로 만든 뒤 구현해 개발을 안정화하다.
03
죽은 Agent 세션, 백로그로 살리는 법2026.07.02
끊긴 세션을 백로그의 보류 결정·후속 작업으로 되살려 연속성을 확보하다.
04
개발이 끝난 SDD 문서, 지울 것과 도메인에 남길 것2026.07.05
병합 후 작업 폴더에 남기지 않을 산출물과 도메인 옆 business 문서로 승격할 것을 가른다.
문서와 Skill
5~8편도메인 문서와 Skill로 Agent가 헤매는 시간을 줄이고, PR에서 문서를 갱신하고, Eval로 Skill을 검증한 기록.
05
문서는 토큰 청구서를 크게 줄이지 않는다 — 대신 Agent가 헤매는 시간을 줄인다2026.07.06
코드에 경계가 없을 때 business 문서로 경계를 만들고, 설계 단계까지 Agent의 탐색 왕복이 줄어드는지 n=1로 측정한 기록.
06
예시가 지시보다 강할 때가 있다2026.07.09
SDD 문서 뼈대를 skill로 고정하려다, skill 안의 지시 충돌과 그대로 복사되는 예시 값을 v1.x → v2 → v2-fix로 좁혀간 기록.
07
business 문서를 PR에서 갱신해보기2026.07.14
diff와 호출 관계로 갱신 대상을 찾고, 코드 근거 확인과 저장 전 검증으로 business 문서를 안전하게 최신화한 첫 실행 기록.
08
Skill 검증을 위한 Eval, 직접 돌려보았다2026.07.22
Trigger·Non-trigger·Procedure 케이스를 직접 실행하며 베이스라인, 검증 비용, 실행형 테스트의 부작용을 확인하다.
방법론과 재검증
9~23편멀티 Agent 운영을 방법론으로 묶어 공유하고, 실무에 다시 적용하고, 모델이 좋아진 뒤 하네스를 다시 재본 과정.
09
멀티 Agent 개발을 실제로 운영해보고 정리한 것들2026.09.01
멀티 Agent 병렬 개발과 작업 격리, 위험도별 검증 Gate를 실제 운영하며 바뀐 기준을 정리한 기록.
10
방법론을 강요하지 않고 공유하는 방법2026.09.13
모두가 지켜야 할 공통 규칙과 개발자가 선택하는 방법론을 가르고, .agentics로 연결 정보만 프로젝트에 남기는 구상.
11
Adaptive SDD를 실무 프로젝트에 다시 적용하면서 손본 것들2026.09.21
실무에 다시 적용하며 리뷰 요청과 반환 형식, 스냅샷 기준, 사람이 실행하는 검증 문서를 다듬은 기록.
12
모델은 좋아졌는데 하네스는 그대로였다2026.10.02
프론티어 모델을 쓰며 기존 하네스가 걸림돌이 된 건 아닌지 의심하고, 걷어내기 전에 먼저 재보기로 한 이유.
13
하네스의 보조 절차 하나만 빼고 돌려봤다2026.10.02
보조 절차 하나만 넣고 빼는 비교를 네 번 돌리고, 세 번 통과에도 판정을 보류한 기록.
14
실험을 멈춘 건 모델이 아니었다2026.10.02
하네스의 보조 절차 비교 실험을 두 번 멈춘 것이 모델이 아니라 격리였던 이유와, 멈춘 뒤에 지킨 것.
15
다시 실험하려고 실험장부터 만들었다2026.10.06
실행마다 새 환경을 만들고 푸는 곳과 채점하는 곳을 나눈 실험장과, 끝까지 간 두 쌍에서 확인한 것.
16
열세 번 돌리고, 판정을 다시 봤다2026.10.13
아직 안 쓴 과제로 한 쌍을 더 돌려본 결과와, 15편 진단 과제의 판정을 검사별로 다시 본 이야기.
17
규칙을 기계에 넘기려고 세어 봤다2026.10.13
규칙 370줄 중 온전히 판정 가능한 건 16줄이었고, 사고 기록에서 가장 많은 유형은 애초에 기계로 넘길 수 없는 것이었다.
18
드디어 방법론 분리 진행2026.10.16
버전만 적어 두는 연결을 만들었지만 앱은 그 길을 쓰지 않았다. 먼저 이어 본 시험 연결을 하나씩 끊어 내며 다시 분리한 과정.
19
Agent 방법론 자기개선 과연 잘 될까?2026.10.16
관측으로 방법론을 고치는 한 바퀴, 손으로 먼저 해 본 점검, 실제 15회 결과, 그리고 이틀 만에 뺀 서명 승인.
20
승인을 늘릴수록 승인은 가벼워졌다2026.10.18
승인을 단단하게 만들수록 가벼워지고 막히기만 해서, 설계 단계 승인을 공통에서 빼고 사람 판단 세 요건만 남긴 과정.
21
방법론을 처음 내놓고, 두 시간 만에 다시 냈다2026.10.18
문서만 담은 첫 공개본을 내고, 구멍과 빈자리를 보고 두 시간 만에 절차·Skill·설치 도구까지 담아 다시 낸 과정.
22
README만 보고 첫 작업까지 가게 해 봤다2026.11.07
README를 다시 쓰고 새 Agent에게 그것만 주고 첫 작업까지 시켜 본 기록. 멈춘 자리에서 바꾼 규칙, macOS 확인, 답안지가 보였던 행동 평가.
23
1.0을 내고, 1분 만에 써 볼 수 있게 했다2026.11.07
방문 통계를 보고 첫 화면과 체험 준비를 손본 기록. 두 Agent에게 작은 버그를 맡기고, 비밀번호 저장에서 멈추는지도 확인했다.
자주 나오는 이름
12편부터 늘어난 이름들| 이름 | 뜻 | 처음 나온 곳 |
|---|---|---|
| 하네스(harness) | 모델 바깥에서 Agent를 붙잡는 절차·검사·규칙 전체. 이 연재에서 만든 방법론이 여기에 해당합니다. | 12편 |
| 하네스의 구성 요소 | 명세, 현행 분석, 변경 계획, 백로그, 독립 리뷰 같은 개별 절차. 통제와 보조 절차를 구분해 필요성을 판단합니다. | 12편 |
| 통제 (헬멧) | 권한, 수정 범위, 승인, 꼭 돌려야 하는 검증. 작업의 위험에 맞춰 거는 것이라 모델이 좋아져도 그대로 둡니다. | 12편 |
| 보조 절차 (보조바퀴) | 모델의 약점을 메우려고 넣은 절차. 지금도 필요한지 다시 재 보는 대상입니다. | 13편 |
| 앱 저장소 | 실제로 만들고 있는 안드로이드 앱. 17편에서는 "실무 프로젝트"라고 불렀습니다. | 18편 |
| 연구 저장소 | 차세대 규칙을 설계하고 실험하는 비공개 저장소. 13~16편의 실험도 여기서 했습니다. 어떤 프로젝트도 직접 읽지 않습니다. | 18편 |
| 앱 전용 규칙 저장소 | 앱이 실제로 쓰는 Agent 작업 규칙을 앱 밖으로 떼어 따로 담은 저장소. | 18편 |
| agent-sdd-kit | 1~7편에서 쓴 작업 등급 규칙과 Skill 두 개를 공개용으로 정리한 저장소. | 7편 |
| adaptive-agentic-sdd | 멀티 Agent 운영 워크플로 전체를 방법론으로 묶어 공개한 저장소. 21·22편의 v1 preview와 23편의 1.0도 여기에 냈습니다. | 9편 |