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

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

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 커맨드 추가

플러그인

• superpowers
• compound-engineering-plugin
• team-attention의 plugin
  • /history-insight
    • 여러 번에 걸쳐 같은 주제(예: 결제 시스템 설계)를 이야기했는데, 그 전체 히스토리에서 패턴/인사이트를 뽑고 싶을 때
    • "우리가 대화 중에 뭘 자주 막혔는지, 어떤 선택 기준을 썼는지" 같은 메타 레벨의 피드백이 필요할 때
    • 지난 세션들 기준으로 나에게 맞는 학습/개발 습관, 다음에 개선할 점 등을 리포트처럼 받고 싶을 때
• vibe-kanban
  • claude-sqaud를 쓰다가 vibe-kanban을 사용 중인데, 에러가 없고 터미널로 관리하는 것 보다 프로젝트별 태스크를 칸반으로 관리할 수 있어서 잘 활용 중이다.

Super Claude

매번 프롬프팅을 손으로 쓰다보면 귀찮고, 어떻게 지시하는게 좋을지 고민될 때가 있다.
이럴 때 Super Claude를 용도에 맞게 쓰면 프롬프팅의 힘을 알 수 있다.

10가지 핵심 기법

YAML Frontmatter (메타데이터) + Markdown Body (행동 지침)

전문가 수준 출력을 위한 각 커맨드의 md를 확인하면 아래와 같이 정의되어 있다.
/sc:brainstorm 참고

1. 명확한 역할 (사고방식 포함)
2. 트리거 (언제)
3. 워크플로우 (어떻게)
4. 행동 패턴 (무엇을)
5. 경계 (Will/Will Not)
6. 예시 (좋은/나쁜)

핵심 차이: 역할 선언 → 사고방식/의사결정 기준까지 확장

Claude Squad

터미널로 사용하다보면 실수로 세션을 끄는 경우가 있다. /resume으로 세션을 재개 할 수 있지만 마지막 출력이 동일하다면 어떤 세션이였는지 가물가물하다.
Claude Squad를 사용하면 내가 명시적으로 세션을 삭제하지 않는 이상 worktree 기반으로 관리되기 때문에 계속 존재한다.
세션별로 작업이 혼합되지 않고 PR도 각각 날릴 수 있어서 편하다.