▲

에이전틱 엔지니어링 패턴

 (simonwillison.net)
5P by GN⁺ 4시간전 | ★ favorite | 댓글 1개
  • Claude Code·Codex 같은 코딩 에이전트 시대의 개발 방식을 정리한 가이드로, 에이전트와 협업하는 새로운 엔지니어링 패턴 제시
  • 코드 작성 비용이 급격히 낮아진 환경에서 개발 습관과 워크플로를 어떻게 바꿔야 하는지 다양한 패턴으로 설명
  • 원칙, 테스트, 코드 이해, 프롬프트 설계 등 에이전트 중심 개발의 핵심 영역을 구조적으로 정리
  • 각 패턴은 실제 코드 예시와 작업 방식, 프롬프트 활용 사례 등을 포함한 실무 중심 패턴 문서 형태
  • 코딩 에이전트 시대의 개발자가 에이전트 기반 코딩 환경을 체계적으로 설계하고 품질을 유지하기 위한 실질적 참고 자료

Agentic Engineering Patterns 개요

  • 코딩 에이전트(Claude Code, OpenAI Codex 등) 와 함께 개발할 때 효과적인 엔지니어링 방법을 정리한 가이드
  • Writing about Agentic Engineering Patterns 소개 글 참고
    • 기존 “Design Patterns” 형식처럼 여러 패턴(chapter) 을 지속적으로 추가하는 구조의 문서
    • 코드 작성 비용이 크게 낮아진 환경에서 개발자의 워크플로와 의사결정 방식 변화를 중심 주제로 구성
    • 블로그 글이 아닌 업데이트 가능한 guide 형식 콘텐츠로 운영되며 지속적으로 확장 예정

1. Principles

  • Writing code is cheap now

    • AI 코딩 에이전트 등장으로 초기 코드 작성 비용이 거의 무료 수준으로 감소
    • 과거에는 코드 작성이 비싸기 때문에 설계·계획 중심으로 개발했지만, 이제는 아이디어를 바로 코드로 시험하는 접근이 가능
    • 코드 생성 비용이 낮아졌지만 좋은 코드(테스트, 유지보수성 등)는 여전히 비용이 존재

  • Hoard things you know how to do

    • 개발자의 중요한 자산은 “무엇이 가능한지 아는 지식의 축적”
    • 다양한 문제 해결 사례와 작은 코드 실험을 저장하고 재사용 가능한 형태로 축적하는 습관 강조
    • 이렇게 모은 코드와 예제는 코딩 에이전트에게 새로운 기능을 만들도록 지시할 때 강력한 입력 자료로 활용 가능

  • Anti-patterns: things to avoid

    • 에이전트가 생성한 코드라도 리뷰 없이 공유하거나 PR을 제출하는 행동은 피해야 할 안티패턴
    • 에이전트가 작성한 PR 설명도 사람이 직접 검증하고 수정해야 함
    • 코드 리뷰어의 시간을 낭비하지 않도록 테스트, 검증 과정, 구현 선택 이유 등을 함께 제공해야 함

2. Testing and QA

  • Red/green TDD

    • 테스트 우선 개발(TDD)은 코딩 에이전트와 함께 사용할 때 특히 효과적인 개발 패턴
    • 테스트를 먼저 작성하면 에이전트가 테스트를 만족하는 방향으로 코드 생성 가능
    • 최소한의 프롬프트로도 정확하고 신뢰할 수 있는 코드 생성에 도움

  • First run the tests

    • 코딩 에이전트와 작업할 때 자동화 테스트는 선택이 아니라 필수 요소
    • 테스트 작성 비용이 줄어든 환경에서는 에이전트가 테스트를 빠르게 생성하고 수정 가능
    • 코드가 실제로 실행되기 전까지는 동작 여부를 보장할 수 없기 때문에 테스트가 중요

3. Understanding code

  • Linear walkthroughs

    • 에이전트가 만든 코드나 프로젝트를 처음부터 끝까지 순서대로 읽으며 구조를 이해하는 패턴
    • 간단한 프로젝트라도 코드 흐름을 따라가며 새로운 기술과 구조를 학습 가능
    • AI 코드 생성이 학습 속도를 늦춘다는 우려에 대해 코드 탐색 자체가 학습 기회가 될 수 있음

  • Interactive explanations

    • 코드나 시스템을 이해할 때 에이전트와 대화하며 설명을 요청하는 방식
    • 질문을 반복하며 코드의 동작 원리와 구조를 점진적으로 파악
    • 코드 이해 과정을 대화형 학습 방식으로 확장하는 패턴

4. Annotated prompts

  • GIF optimization tool using WebAssembly and Gifsicle

    • WebAssembly와 Gifsicle 기반 GIF 최적화 도구를 만드는 프롬프트 예제 포함
    • HTML, JavaScript, CSS를 포함한 단일 페이지 도구 구현 방식 제시
    • 실제 프롬프트와 코드 예제를 통해 코딩 에이전트 활용 방식 설명

5. Appendix

  • Prompts I use

    • 실제로 사용 중인 코딩 에이전트 프롬프트 예시 모음
    • 다양한 작업에 활용되는 실전 프롬프트 패턴 정리
    • 에이전트와 협업할 때 사용할 수 있는 실용적인 템플릿 제공
▲
GN⁺ 4시간전  [-]
Hacker News 의견들

  • 우리는 또다시 같은 일을 반복하려는 것 같음
    단순하고 합리적인 개념들 — 예를 들어 “테스트를 먼저 작성하라”, “작고 조합 가능한 모듈을 만들라” — 을 복잡한 이름으로 포장하고, 그걸로 컨설턴트 산업을 만들어낼 것 같음
    그런데 이번엔 그 대상이 “말하는 기계”임. 그냥 말로 시키면 되는 세상임

    • COBOL도 비슷한 약속을 했었음. 인간이 읽기 쉬운 언어라 프로그래머가 필요 없을 거라 했지만, 결국 문제를 세분화하고 해결하려면 사람이 프로그래머처럼 사고해야 했음. 즉, 언어가 인간 친화적이라고 해서 프로그래머가 사라지는 건 아님
    • 이번에도 AI 붐의 주기가 반복될 것 같음. 지금은 비판하면 “이해 못 한다”는 반응이 돌아오지만, 곧 문제들이 터져 나올 것임. 특히 “AI가 너무 많은 코드를 생성해서 인간도, AI도 감당 못하는 상황”이 생길 것임. 그때쯤이면 또다시 패턴과 안티패턴, 그리고 그걸 해결한다는 컨설턴트들이 등장할 것임
    • AI가 영어로 말하고 이해하니 인터페이스의 명확성이 떨어짐. CLI처럼 강력하지만, 어떤 방식이 효과적인지 불분명함. 그래서 “무엇을 어떻게 시키면 좋은 결과가 나오는지”를 문서화하고 공유하는 게 중요함. 단, 그게 또다시 OOP 코칭 산업처럼 변질되지 않게 해야 함
    • 맞음. 또 그렇게 될 거고, 이번엔 훨씬 빠르게 진행될 것임. 블로거 → 강연자 → 책 → 컨설턴트 → 인증기관 순으로 10년짜리 사이클이 몇 년 안에 압축되어 나타날 것임
    • 글 제목이 복잡하다는 지적엔 동의하지 않음. 다만 “그냥 말로 시키면 된다”는 오해가 문제임. 실제로는 사람마다 결과가 천차만별임. 결국 “인간에게 좋은 개발 습관이 AI에게도 좋다” 는 교훈이 나오고 있음. AI는 인간 같지만 인간이 아님. 그래서 더 많은 설명이 필요함

  • Simon에게 묻고 싶음 — “코드가 싸진 세상에서 코드 리뷰는 어떻게 해야 하는가?”
    팀원들이 구조를 이해하지 못한 채 “작동하니까 됐잖아” 식으로 접근함. 리뷰는 점점 커지고, 나는 병목이 됨. AI 리뷰어를 대리로 쓰는 방법도 고민했지만, 인간적인 감각이 사라지는 게 싫음

    • 정말 흥미로운 주제임. 코드 생성 속도가 빨라지면 리뷰가 병목이 됨. 코드가 싸다면 리뷰 기준을 낮출 수도 있겠지만, 나는 오히려 더 나은 품질을 원함. 특히 보안 검토는 절대 생략할 수 없음. 대규모 조직의 보안팀처럼 체계적인 접근이 필요할지도 모름
    • 에이전트 기반 리뷰를 쓰려면 맥락 세팅이 중요함. 계획 → 실행 → 테스트/수정 → 리뷰/리팩터 → QA 가이드 생성의 루프를 돌리면, 코드뿐 아니라 문서와 테스트 지침까지 함께 진화함
    • “작동하니까 됐잖아”는 기술 문제가 아니라 조직 문화 문제임. 어떤 회사는 여전히 읽기 쉬운 코드를 중시함. 그게 경쟁력이 될 수도 있음
    • 나는 정적·동적 분석 자동화에 투자함. 커스텀 린트 규칙, 강한 타입 검사, mutation testing 같은 품질 도구를 적극 활용함. 리뷰만으로는 느리고 비효율적이므로, 조기 피드백 자동화가 핵심임
    • 이런 태도는 쉽게 바뀌지 않음. 차라리 소프트웨어 품질을 중시하는 팀으로 옮기는 게 나을 수도 있음

  • 나는 AI를 주로 보일러플레이트 코드나 문서 문제 해결용으로 씀
    에이전트형 작업도 해봤지만 결과물은 아직 신뢰하기 어려움. 그런데 어떤 사람들은 “이제 거의 코드를 안 쓴다”고 함. 그 간극이 흥미로움

    • 나에겐 AI보다 직접 코딩이 더 빠를 때가 많음. 계획 세우고 실행시키고 검증하는 과정이 오히려 느림. 하지만 대규모 리팩터링은 AI가 훨씬 빠름
    • 최근 몇 달 사이 에이전트 성능이 급상승했음. 이제는 단순 자동완성 수준을 넘어 전체 기능 구현까지 가능해짐
    • AI 코드에 “이건 AI가 쓴 거네”라는 ‘이질감(eww)’ 을 느끼는 개발자와 그렇지 않은 개발자의 차이로 설명할 수 있을 듯함
    • 결국 작업의 종류에 따라 AI가 잘 맞는 경우와 아닌 경우가 명확히 갈림
    • 나도 첫 결과물은 마음에 안 들지만, 리뷰 루프를 여러 번 돌리면 품질이 확실히 올라감. AI끼리 리뷰를 시키거나 테스트 기준을 명확히 하면 훨씬 나아짐

  • 최근 에이전트형 코딩 루프를 실험 중임
    예를 들어 fesh 프로젝트에서 “리눅스 바이너리를 더 작게 압축하기”를 목표로 함. 테스트가 명확한 문제라 AI 루프에 적합했음
    배운 점은 다음과 같음:

    • 테스트 하니스가 전부임. 검증 루프가 없으면 방향이 틀어짐
    • AI가 실험적으로 시도하도록 두는 게 중요함
    • 세션 간 .md 스크래치패드를 남겨야 학습이 이어짐
    • 테스트가 정말 중요함. AI는 이상한 방식으로 실패하므로 테스트 자동 생성을 적극 활용해야 함
    • 테스트 없이는 루프의 결과를 신뢰할 수 없음. 결정적 검증 절차가 필수임
    • 결정 로그와 거부 로그를 분리해 기록하는 게 유용했음. 특히 rejections.md가 더 가치 있었음. “왜 이 접근을 버렸는가”를 남겨야 AI가 같은 실수를 반복하지 않음
    • 브라우저 자동화에서도 비슷함. 기능적 검증뿐 아니라 행동적 검증(인간처럼 보이는가) 을 추가해야 유용해짐. 그리고 .md 로그는 다음 세션의 품질을 크게 높임

  • 테스트 섹션에서 LLM이 만드는 ‘자기충족적 테스트’ 문제를 다뤘으면 좋겠음
    테스트가 실제로는 아무 것도 검증하지 않거나, 심지어 하드코딩된 값으로 통과하는 경우가 있음. 인간이 AI를 엄격한 테스트 습관으로 유도해야 함

    • 구체적인 예시가 궁금함. 단순한 논리 오류가 아니라, 겉보기엔 괜찮지만 실제론 무의미한 테스트를 말하는 듯함
    • 나쁜 테스트는 없는 것보다 더 위험함. 한 번 신뢰가 깨지면 전체 테스트 스위트에 대한 믿음이 무너짐
    • 그래서 mutation testing이 중요함. 코드가 변형돼도 테스트가 통과하면 그건 나쁜 테스트임
    • AI에게 코드 일부를 의도적으로 바꾸게 해서 테스트가 실패하는지 확인하면 됨. 실패하지 않으면 쓸모없는 테스트임
    • 물론 인간에게도 이런 테스트를 쓰게 하는 건 쉽지 않음

  • 매 세대의 LLM이 나오면 기존 교훈이 모두 무효화되는 느낌임
    LangChain처럼 구형 모델의 한계를 우회하려 만든 복잡한 구조들이 GPT-3.5 이후엔 불필요해졌음. 곧 단일 에이전트로도 충분히 모든 걸 처리할 수 있을지도 모름

    • 그래서 나는 모델 버전에 의존하지 않는 패턴을 정리하려 함. 예를 들어 red/green TDD는 곧 모델이 스스로 하게 될 수도 있지만, 개념 자체는 여전히 유용함
    • 결국 모든 게 ClaudeVM 같은 형태로 수렴할 수도 있음
      관련 글 보기

  • 에이전트 엔지니어링 논의에서 자주 빠지는 점이 있음
    대부분의 교훈이 보편적 진리처럼 말해지지만, 실제로는 팀 규모, 코드베이스 성숙도, 테스트 수준, 리스크 허용도에 따라 달라짐. 중요한 건 “언제 이 패턴이 통하는가”를 명확히 밝히는 것임

    • 그래서 나는 책이 아니라 웹사이트 형태로 패턴을 정리함. 계속 업데이트하며 적용 범위를 명시할 예정임
    • 컨설턴트로서 여러 코드베이스를 다뤄보면, Claude Code의 성능은 코드베이스 품질에 따라 극단적으로 달라짐. 강한 타입과 테스트가 있는 프로젝트는 거의 완벽히 작동하지만, 느슨한 자바스크립트 환경에서는 별로임
    • 그래도 일부 패턴은 보편적임. 예를 들어 독립적인 소스 오브 트루스(harness) 를 두는 건 어디서나 유효함. showboat, rodney 같은 도구가 그걸 돕고 있음

  • 요즘 “에이전트 팀 프레임워크”가 하루에도 수십 개씩 쏟아짐
    초창기 소프트웨어 공학처럼 혼란스러운 실험기임. 하지만 결국 몇 가지 패턴이 표준으로 자리 잡을 것임.
    우리 팀은 인간 팀처럼 접근하는 게 효과적이었음 — 먼저 제품 명세서(spec) 를 작성하고, AI로 다듬은 뒤, 그걸 기반으로 역할이 분리된 에이전트 흐름에 넘김

  • 오늘 학부 수업에서 CPU·GPU 아키텍처의 진화를 강의했음
    과거엔 Moore’s Law 덕에 하드웨어가 모든 걸 해결했지만, 이제는 병렬성이 핵심임.
    Simon이 말한 “코드는 싸다”는 개념도 이와 비슷한 패러다임 전환임.
    병렬 하드웨어 시대에 효율적인 코드가 완전히 달라졌듯, AI 시대엔 개발 프로세스 자체가 바뀔 것임. 이를 먼저 이해한 사람이 10~100배의 이득을 볼 것임

  • 우리 팀에선 ‘중간중간 인간 검증을 넣는 루프’ 가 가장 실용적이었음
    완전 자율형 에이전트는 테스트는 통과하지만 암묵적 불변조건을 깨는 경우가 많음.
    그래서 되돌릴 수 없는 결정 직전에 인간이 개입하도록 함.
    다만 “무엇이 되돌릴 수 없는가”를 AI가 이해하게 만드는 게 또 다른 과제임.
    CLAUDE.md 같은 문서 외에 암묵적 코드베이스 규칙을 전달하는 체계적 방법을 찾고 있음

답변달기