에이전틱 프로그래밍에 가까워지기

에이전틱 프로그래밍을 위해 내가 사용하는 방법을 기록하고 개선하기 위해 작성한다.

끝난 건 타이핑이지, 엔지니어링이 아니다. 좋은 설계의 레버리지는 커졌고, 나쁜 설계의 피해도 커졌다. 쇼의 주인공은 AI가 아니라 AI를 잘 다루는 엔지니어다.

2026-03-16

업무적으로는 AI-TPM을 계속해서 만들고 있고, TPM 모드에서 의도한대로 프로젝트와 소스(노션, 슬랙 등)들을 정상적으로 참조하는지 모니터링 툴을 이용해서 확인하고 의도한대로 호출되지 않으면 다시 교정하는 작업을 반복 중이다.
호출할 때 마다 지시한대로 움직이지 않을 확률이 존재하기 때문에, 이걸 정량적으로 확인하기 위한 시나리오 실행 툴도 만들고 있다.

사용 흐름은 아래와 같다.

1. 플러그인의 domain-setup 커맨드로 참조할 프로젝트들의 도메인들을 세팅한다.
2. AI-TPM 모드를 실행할 위치에서 project-paths.json을 작성한다.
3. project-paths.json에 프로젝트의 절대경로와 참조할 소스 링크(노션, 슬랙 링크 등)을 작성한다.
4. domain-enrich 커맨드를 이용해 project-paths.json에 작성한 프로젝트와 소스에 대한 description을 작성한다.
5. domain-scenario-create 커맨드와 세팅된 도메인 정보를 이용해서 시나리오를 생성한다.
6. domain-scenario-run 커맨드로 작성된 시나리오를 N회 실행하여 보고서를 출력한다.

시나리오를 생성하려면 도메인과 코드베이스에 대한 이해가 필요해서, 다른 분들에게 사용 가이드를 전달하고 피드백을 적용하면서 발전시킬 예정이다.
최종적인 목표로는 회의에 참석시켜서 궁금한 것에 대한 빠르고 (꽤) 정확한 대답과 회의에 나온 컨텍스트를 적용해서 적용 가능 여부 & 변경 범위 파악 & 작업 진행을 시키는 것이 목표다.

이렇게 만들면서 느낀 점과 보완해야 할 점들이 있다.

1. 플러그인을 운영하면서 수정하고 테스트하는 사이클을 만들기가 어렵다.
   • 배포한 뒤 다시 업데이트 받고 테스트하기에는 너무 번거롭다.. 아니면 로컬 캐시를 직접 수정해야 하는데, 로컬 캐시의 플러그인과 로컬 플러그인의 내용이 동기화되지 않을 수 있지 않을까 하는 마음에 꺼려했지만, 로컬 캐시 플러그인을 빠르게 수정하고 테스트하는게 최선인 것 같다.
2. 바이브코딩에 대한 가드레일이 부족하다.
   • 제일 시급한건 내가 생각하는 클린 코드, 클린 아키텍처, 트랜잭션 분리 등 나의 지식을 그대로 담은 에이전트(또는 컨벤션)를 만들어야한다.
   • superpowers를 제외한 나만의 워크플로가 없다. 스스로 작업 단위를 어떤 순서대로 나누는지 잘 확인해서 이걸 본따 스킬로 만들어야한다.
3. 내가 바이브코딩을 진행하는 습관을 되돌아봐야 한다.
   • 작업을 태스크별로 쪼개서 병렬로 진행하는 것, 그러면서 내가 검수해야 할 내용들은 꼼꼼히 읽어보는 습관을 들여야 한다.
   • 한번씩 읽기에 지치면 그냥 진행할 때가 있는데 그런 경우 잘못된 방향을 다시 고치는게 비용이 더 크다.
   • 작업 단위를 잘 나누고 구현전 스펙을 자세하게 작성하고 구현 계획을 꼼꼼하게 읽는 것. 그리고 구현 계획 검수에 대한 비용을 줄이고 싶다면 제 2의 정현준을 만들어서 에이전트로 검증해야 한다. 이때 훅을 사용하는 방법을 고안해봐야한다.

2026-03-02

• 에이전틱 엔지니어링 시대의 생존 스킬 9가지
  • 요구사항을 명확히 쪼개고 엣지 케이스를 정리하는 능력
  • 아키텍처와 컨텍스트 설계 능력
  • AI 기준의 '완료'가 아니라 개발자, 지시하는 사람으로서의 '완료'를 정의하는 능력
  • 실패를 복구하는 능력
  • 관찰 및 롤백 가능한 단위로 작업을 나누고 실행시킬 수 있는 능력
  • 개인의 기억이 아니라 팀, 더 나아가 사내 구성원들의 기억이 에이전트에게 전달되는 구조
  • 병렬로 매니징하는 능력
  • 추상화 게층 설계 능력 (엔지니어링은 단거리 경주가 아니라 복리 게임)
• AI가 규칙을 "알잘딱" 지키는 백엔드 레포 만들기
  • AI는 지시사항과 문서를 잘 안지킨다.
  • 자연어의 모호성, 규칙 충돌 등
  • 결정론적 코드 제어 : 아키텍처 강제, 린트 (의존성 규칙, 네이밍, 인터페이스 패턴, 구조), 테스트
  • 대칭성 (모든 계층이 동일한 패턴을 따르도록)
  • 규칙을 문서로 적지말고 DDD를 활용하여 결정론적 검증 시스템을 구축하라

2026-02-17

사내 에이전틱 코딩 TF를 맡게 됐다. 개인적으로 주최한 스터디가 회사의 방향과 맞아떨어지면서 자연스럽게 TF로 전환됐다. 요즘은 AI TPM과 에이전틱 코딩 컨벤션에 관심을 두고 있다.

AI 관련 기술이 쏟아지는 상황에서 백엔드 개발자로서 가장 의미 있는 작업이 뭘까 고민하다 보니 에이전틱 코딩에 관심을 가지게 됐다. 현재 풀고 싶은 문제는 크게 세 가지다.

1. 오케스트레이션 모니터링 : 클로드 코드가 에이전트/스킬/훅을 의도대로 호출하는지 확인할 수 있는 도구
2. 도메인 컨텍스트 관리 : 도메인 지식과 코드베이스의 상호 의존성을 계층화하여 AI에게 전달하는 방법
   • CLAUDE.md 중첩, 라우팅 레이어, 서브에이전트 전용 컨텍스트 삽입, 상황별 에이전트 팀즈 활용 등
3. 검증 가능성 확보 : 에이전트 동작을 테스트할 수 있는 방법
   • 중복된 CLAUDE.md를 읽었는가?
   • 의도한 스킬이 트리거됐는가?
   • 서브에이전트에 올바른 컨텍스트가 전달됐는가?
   • 도메인 규칙을 실제로 적용했는가?

위 문제를 해결하기 위해 아래의 문서를 차근차근 읽어가고 있다.

Codex 팀의 Ryan Lopopolo는 이걸 "Harness Engineering"이라고 부릅니다.
엔지니어의 역할이 코드를 작성하는 사람에서, 에이전트가 일할 수 있는 환경을 설계하고 의도를 명세하고 피드백 루프를 만드는 사람으로 바뀌는 겁니다.
Humans steer, agents execute

• OpenAI Harness
• OpenAI Harness Engineering
• OpenAI Harness 5원칙 - toneylee
• PLANS.md
• ARCHITECTURE.md
• AI는 좋은 코드를 강제한다
  • 에이전트는 지치지 않고 꽤 똑똑하게 코딩하지만, 결국 놓여 있는 환경만큼만 잘한다.
  • 지저분한 코드베이스에서 자기가 망쳐놓은 걸 알아서 수습하는 능력이 약하므로, 사람이 더 촘촘한 가드레일을 깔아줘야 한다.
  • 그래서 그동안 “시간 없어서 미뤘던” 좋은 코드/인프라 작업을 이제는 진짜로 투자해야 하고, 이것을 에이전트 시대의 필수 엔지니어링 과제로 로드맵에 넣어야 한다.
  • 100% 테스트 커버리지 : 에이전트가 건드린 모든 코드 라인의 동작을 반드시 예시(테스트)로 검증하게 만드는 장치로 100% 커버리지를 요구
  • 파일/디렉터리 구조와 작은 모듈 : 에이전트는 결국 파일 시스템을 보며 탐색하므로, 의미 있는 디렉터리/파일 이름과 잘게 쪼개진 파일이 중요한 인터페이스가 된다.
  • 타입과 자동화된 베스트 프랙티스 : 린터/포매터를 최대한 엄격히 돌리고, 작업 종료나 커밋 시 자동으로 고치게 만드는 등 가급적 많은 규칙을 자동으로 강제한다.
  • API는 OpenAPI 기반 타입 세이프 클라이언트, 데이터는 타입,체크,트리거, ORM은 Kysely 같은 타이핑 좋은 툴을 통해 끝단까지 타입을 관통시키는 식으로 설계한다.

2026-02-10

처음에는 아키텍처, 클린 코드 같은 "사람을 위한 고민"이 AI에게 도움이 될지 의문이었다.
하지만 사람에게 인지부하가 낮다는 건 AI 컨텍스트도 작게 차지한다는 의미라는 걸 깨달았다.

멀티 모듈의 특정 모듈, 아키텍처의 특정 레이어, 특정 패키지에는 우리가 목적과 책임을 부여한다.
이 목적과 책임을 에이전트별로 구분할 수 있다면, 에이전트의 컨텍스트 윈도우도 효율적으로 사용할 수 있다.
Claude Code의 Agent Teams(실험적 기능)를 사용해보면서 결국 에이전트를 어떻게 배치하고 활용하느냐가 핵심이라는 생각이 들었다.

테스트 코드, 클린 코드 같은 기술적 컨벤션은 이미 많은 SKILL이 대중화되어 적용하기 쉽다.
그런데 도메인 지식은 어떻게 계층화하여 AI 컨텍스트에 삽입할지가 고민이다.

부문장님의 forge-prompt를 활용해서 도메인 에이전트를 설계해볼 생각이다.
핵심 비즈니스의 도메인 정보를 자산화하는 것이 중요한 과제처럼 느껴진다.
꾸준한 자산화를 통해 결국 도메인 정보도 AI에게 전적으로 의지할 수 있지 않을까?

비즈니스별로 AI 컨텍스트를 잘 관리할 수 있다면, AI TPM(Technical Project Manager)을 만들 수 있지 않을까?
프론트, 이커머스, OMS 프로젝트에 AI 컨텍스트 구조를 설계하여 TPM을 구현하는 것이 현재 목표다.

2026-02-03

요즘 애플리케이션 아키텍처에 대한 고민을 하다가 문득, 이런 아키텍처 작업은 사람을 위한 행위인데 AI를 위한 고민이 중심이 되어야 하지 않나?
사람이 코드를 언제까지 읽을 수 있을까? 아직 검수는 필수이지만 대부분 코드에 대한 이해를 AI에게 의존하고 있는데 애플리케이션 아키텍처가 중요할까?
AI친화 아키텍처를 고민해야하지 않을까? 라는 생각을 했다.
결국 아키텍처도 책임과 목적을 분리하고 인지부하를 낮추는 행위이기 때문에 AI의 토큰 절약이나 컨텍스트를 너무 많이 차지하지 않게 하여 해결이 필요한 부분의 적절한 크기만큼 메모리에 로딩하게 하는것도 전략이기 때문에 결국 아키텍처 고민도 적절하다고 생각하긴 한다.
하지만 에이전틱 프로그래밍을 이루기 위해 어떤 문서를 어디에 위치시키고 어떤 전략을 가져야할까를 고민하게 됐다.

• 프롬프트 엔지니어링 개요
• 의도를 드러내는 이름
• OMS에서 Claude AI를 활용하여 변화된 업무 방식
• "배민은 이제 노가다 안 합니다" 1시간 업무를 1분만에 끝내는 AI 자산화의 비밀(우아한형제들 임동준님)

1. ADR.md : 의사결정 문서
2. TODO.md : 큰 작업을 한 번에 끝내기 힘든 경우
3. CLAUDE.md : 모든 프롬프팅에서 공통적으로 주입하기 위한 내용
   • 추가로 주입하고 싶은 정보가 있으면 다른 파일들 링크 추가해도 됨
4. SKILLS : 한 번에 너무 많은 정보를 전달하기 보다는 필요한 작업에 필요한 내용을 주입하기
5. 커스텀 커맨드 : 예를 들어, 세션에서 나눈 기술적 의사결정을 ADR.md에 정리하도록 /adr 커맨드 추가