• 원본: https://news.hada.io/topic?id=25949

• 목적: 원본 아티클 기반으로 현재의 AI 활용법에서 개선할 부분 찾기

  • #Claude_Code, #프론트엔드_개발

• 글 내용이 아닌 개인 의견은 하이라이팅

핵심원칙

큰그림/뼈대 먼저

• 핵심 요구 사항이 무엇인지 정리 => 핵심만 먼저 구현

  • 뼈대(핵심 요구 사항)를 바탕으로 점점 살(상세 스펙)을 붙여나가는 방식

• 활용중

  • Claude Code Plan Mode => Shift + Tab으로 읽기 전용

  • 스펙 파일 활용(`spec.md`)

  • What/why에 집중(how는 뒤로 미루기)

    • 결과물 보면 구현 방법을 시정해줘야 할때가 있는데 처음에는 How를 신경쓰지 말라는 뜻인듯

• 개선 필요

  • 기존에는 spec 파일을 삭제했는데, 삭제 하지 않고 유지하기

    • 이점: 히스토리 길어지거나 에이전트 재시작시 망각을 줄일 수 있음

스펙을 전문적으로 작성하기

• AI 스펙을 단순 메모 모음이 아니라, 명확한 섹션을 가진 문서로 구조화하기

  • 시스템 설계 문서 => AI에게 잘 맞음

• 효과적인 스펙의 특징 6가지 (Github의 에이전트 설정 파일 분석 결과)

  • Commands

    • 실행 가능한 명령어를 문서 앞부분에 배치

  • Testing

    • 테스트 실행 방법, 사용하는 프레임워크, 테스트 파일 위치, 기대하는 커버리지 수준을 구체적으로 명시

  • Projects Structure

    • 소스 코드, 테스트, 문서의 위치를 명확히 구분

  • Code Style

    • 스타일을 장황하게 설명하는 것보다 실제 코드 스니펫 하나가 훨씬 효과적

    • 네이밍 규칙, 포매팅 기준, 바람직한 출력 예시를 함께 제시

  • Git Workflow

    • 브랜치 네이밍 규칙, 커밋 메시지 형식, PR 요구사항을 명시하면 에이전트도 그 흐름을 따름

  • Boundaries

    • 건드리면 안되는 영역 분명히 지정(프로덕션 설정, 특정 폴더)

• 기타

  • 스택 구체적 명시

  • 일관된 형식 사용

  • 스펙 키트 활용한 스펙 드리븐 개발(https://github.com/github/spec-kit)

  • agent.md를 활용한 에이전트 페르소나 정의(@docs-agent(기술 문서), @test-agent(QA), @security-agent(코드 리뷰)같은 역할 분리 가능)

  • 에이전트 경험(AX)을 고려한 설계(https://modelcontextprotocol.io/docs/getting-started/intro)

  • 스펙을 한번 작성하고 끝내지 않고 지속적으로 업데이트(살아있는 문서)

• 활용중

  • Project Structure: 소스 코드의 디렉토리는 명확하게 구분하여 사용중

  • 스택을 구체적으로 명시하고 일관된 형식(markdown)으로 스펙 작성

• 개선 필요

  • Commands: 어차피 Commands는 package.json에 기록되어 있어서 알아서 읽을텐데 스펙 문서에 따로 적어줘야 할 필요가 있을까?

  • Testing: 테스팅 작성은 안해봤는데 해봐야겠다.

  • Code Style: 지금까지는 commit 직전 Lint 돌렸는데, 애초에 코드를 스타일에 맞게 생성하거나 LLM-as-a-Judge 활용

  • Git Workflow: 지금까지 브랜치 생성, 커밋 메시지 입력, PR 생성은 직접 했음. 코드 생성 외의 영역에도 AI 활용해보기

  • Boundaries: 이건 따로 안했던 것 같은데 할 필요가 있는지 아직은 잘 모르겠음. 올라가면 안되는 파일이 올라가거나 지우면 안되는 파일을 지운 적이 없음. 이건 내가 소규모 개인 프로젝트만 경험 해봐서 그런듯

  • 스펙 키트, agent.md 등 도구 활용하기

  • 스펙을 일회성으로 사용 하지 않고 남겨두며 업데이트 하기

태스크를 모듈화된 프롬프트와 컨텍스트로 분할

• 분할 정복

• 분할 하는 이유

  • 토큰 한계에 걸릴 위험

  • 지시의 저주: 연구에 따르면 많은 요구사항을 동시에 만족시키라는 요청에 어려움을 겪음(10개의 상세 규칙 요청 => 처음 몇개만 지키고 뒤쪽은 점점 무시)

• 활용중

  • 각 프롬프트를 하나의 태스크/섹션에 집중(예: 인증 태스크와 데이터베이스 스키마 변경을 한 번에 섞지 않기)

  • 인라인 지시문과 코드 TODO(미니 스펙 역할) 활용

• 개선 필요

  • 서브에이전트, 병렬 에이전트(여러 에이전트 동시에 돌리는 방식, 서로 겹치지 않는 작업에 병렬로 에이전트를 투입) 활용

  • 스펙 분할

    • 스펙 문서를 여러 개로 나누기(Backend API Spec”과 “Frontend UI Spec”을 별도 섹션으로 분리, 백엔드 작업을 할 때는 백엔드 스펙만 건네기)

자가 검사, 제약 조건, 인간 전문성 내장

• 스펙의 역할: 스펙은 TODO 리스트가 아니다.

  • 스펙 ≠ 에이전트의 할 일 목록 / 스펙 = 품질을 관리하는 가이드

  • 좋은 스펙은 실수 지점을 미리 짚어 가드레일 역할을 함

• 스펙이 담아야 하는 것

  • 각종 주의사항(도메인 지식, 엣지 케이스 등)

  • 이것들이 없으면 맥락 없는 진공 상태에서 작동하게 됨

• 3단계 경계 시스템 (Github의 에이전트 설정 파일 분석 결과)

  • ✅ Always do

    • 묻지 않고 수행

      • 커밋 전 테스트 실행

      • 네이밍 컨벤션 준수

      • 오류는 모니터링 서비스에 로깅

  • ⚠️ Ask first

    • 인간의 승인이 필요한 작업

      • DB 스키마 수정

      • 새 의존성 추가

      • CI/CD 설정 변경

  • 🚫 Never do

    • 하드 스톱 영역

      • 시크릿 키 커밋

      • API 키 커밋

      • node_modules 편집

      • 테스트 제거

• 자가 검증 장려

  • 에이전트가 스스로 결과를 점검하도록 유도

    • 코드 생성 후 단위테스트나 린팅 직접 실행하도록 워크플로우에 포함

    • 요구사항 미충족 및 구현 누락 재확인하도록 지시(프롬프트 수준)

• LLM-as-a-Judge

  • 심판 역할의 두번째 에이전트를 만들어서, 첫번째 에이전트의 출력 검토를 맞기는 것

  • 코드 스타일, 가독성, 아키텍처 패턴 준수처럼 자동화하기 어려운 경우 활용

• 적합성 테스트

  • 적합성 스위트 구축하고, 스펙에 이를 통과해야 함을 명시하기

  • 적합성 스위트란?

    • 언어에 의존하지 않는 테스트

    • 모든 구현이 반드시 통과해야 하는 계약 역할

  • 예: API를 만드는 경우

    • 적합성 스위트가 예상 입력과 출력을 정의

    • 에이전트가 생성한 코드는 이를 모두 만족해야함

      • 스펙의 Sucess 섹션에 적합성 스위트를 통과 해야함을 명시

      • “conformance/api-tests.yaml의 모든 케이스 통과 필수”

• 스펙에 테스트 활용

  • 스펙이나 프롬프트 흐름에 테스트 계획이나 실제 테스트 포함

  • TDD처럼 테스트 케이스를 통해서 요구사항 명확히 하기

  • 서브 에이전트 구성이라면 테스트 에이전트를 두는 방법도 있음

    • input: 스펙, 에이전트의 출력 코드

    • output: 테스트 결과

• 도메인 지식 반영

  • 스펙에 현실적인 인사이트 담기

    • 예: 이커머스 에이전트 만들때 “products”와 “categories”가 다대다 관계라는 점을 명시

  • 특정 라이브러리가 까다롭다면, 자주 빠지는 함정이나 주의점도 함께 명시

    • 예: “라이브러리 X 사용 시 버전 Y에서 메모리 누수 문제가 있으니 우회책 Z 적용”

• 간단한 태스크에는 미니멀리즘

  • 언제 단순해야 하는지 아는 것이 전문성

  • 작업의 복잡도에 따라 스펙의 밀도 조정(과도한 스펙x)

• 인간 = 최종 품질필터 역할

  • 사람 인턴을 관리하는 것과 비슷함

  • 에이전트에 권한을 주되, 최종 품질 책임은 개발자에게 있음

  • 요구사항을 충족했더라도 느낌이나 맥락이 안맞으면 자신의 판단 신뢰하기

    • 스펙을 다시 쓰거나, 결과물을 직접 손보기

• 활용중

  • 요구사항 미충족 및 누락을 재확인하도록 지시(프롬프트 수준)

  • 느낌이나 맥락이 안맞으면 직접 수정하거나 다시 요구하고 있음

• 개선 필요

  • 3단계 경계 시스템 적용해보기

  • 코드 생성 후 자가 검증 하도록 설정하기

    • 코드 생성 후 단위테스트나 린팅 실행을 워크플로우에 포함

  • 도메인 지식이나 주의점 스펙에 명시해보기

  • 심판 역할의 서브 에이전트 활용(LLM-as-a-Judge)

  • 테스트 전담하는 서브 에이전트 활용

테스트, 반복, 스펙 진화 (올바른 도구 활용)

• 스펙 작성, 에이전트 구축은 반복 루프임

• 초기 스펙을 그대로 사용x 수정하며 업데이트

• 지속적 테스트

  • 테스트를 모든 구현이 끝날때까지 미루지 말고, 가능한 부분을 테스트하기(함수 단위 테스트, 간단한 수동 검사)

  • 자동화 테스트가 있다면 에이전트가 직접 실행하도록 할 수 있음(npm test)

  • 테스트 결과를 보고 실패가 있다면

    • 먼저 스펙이나 프롬프트 수정

    • 테스트 결과를 다음 프롬프트의 입력으로 사용

  • 에이전틱 루프: 코드 > 테스트 > 수정 > 반복

• 스펙 자체 반복

  • 요구사항 누락이나 에이전트 오해가 있으면, 스펙 먼저 수정

  • 수정된 스펙을 에이전트와 동기화

  • 가능하면 커밋 메세지나 버전 히스토리 남겨서 무엇이 왜 바뀌었는지 추적 가능하도록 하기

• 컨텍스트 관리 및 메모리 도구 활용

  • AI에이전트의 컨텍스트, 지식 관리를 돕는 도구가 빠르게 발전 중

  • RAG(검색 증강 생성) 패턴 활용

    • 에이전트가 지식 베이스에서 필요한 정보만 즉시 가져오는 것이 가능

• 신중한 병렬화

  • 각 태스크가 독립적이 않거나 명확히 분리되어 있지 않으면 충돌 발생 가능

    • 태스크가 독립적인 예: 에이전트1 - 코드 생성 / 에이전트2 - 테스트 작성

  • 두 에이전트가 동시에 파일 수정하지 않도록 제한 필요

  • 초반에는 적은 개수로 시작하는 것이 현실적(2-3개)

• 버전 관리와 스펙 잠금

  • 버전 관리 도구로 에이전트의 작업을 꼼꼼히 추적할 것

  • AI를 많이 활용할수록 버전 관리의 중요성이 더 커짐

  • 스펙 파일 자체도 커밋해서 이력 남기기(버전 관리)

    • 개발자가 변화 추적 가능

    • 에이전트도 git diff해서 변경 맥락을 이해할 수 있음(LLM은 diff 해석에 상당히 능숙함)

• 비용과 속도 고려

  • 대형 모델 & 긴 컨텍스트 쓰는 작업 => 느리고 고비용

  • 전략적 모델 선택

    • 초안, 반복 작업 => 저렴한 모델

      • 로컬 모델이나 소형 API 모델

      • 예: GPT-4o mini, Claude Haiku

      • 프레임워크를 사용하면 Claude Haiku로 모델 변경 가능

    • 최종 출력, 복잡한 작업 => 유능한 모델

      • 예: GPT-4, Claude

  • 토큰 사용량 관리

    • Needle in a Haystack

      • 쓸모없는 정보까지 제공하면, 효율성이 떨어짐

      • 토큰 수 ↑, 정확도 ↓, 실수 가능성 ↑

    • 사용량 관리 방법

      • 요구 사항이 명확해야 함

        • 체크가 필요한 파일, 작업 범위 명확히 제공

      • 점진적인 작업 요청하기

        • 한꺼번에 큰 작업 요청x

      • 서브에이전트 활용하기

        • VoltAgent 등 에이전트 팩 활용 or 직접 만들어서 활용

      • Claude Code 명령어 적절히 사용

        • /compact # 이전 대화를 요약해서 토큰 절약

        • /clear # 새로운 작업 시작 시 컨텍스트 초기화

• 모든 것을 모니터링 & 로깅

  • 에이전트 워크플로우가 복잡하다면, 에이전트 행동과 출력 로그가 필수

  • 로그를 통해 오류 발생 및 의도에서 벗어났는지 확인 가능

    • 스펙이나 지시가 어디서 잘못 해석됐는지

    • 많은 프레임워크가 트레이스 로그, 단계별 사고 과정을 출력하도록 지원함

• 학습과 개선

  • 프로젝트를 통해서 스펙 작성 역량 키우기

    • AI가 어떤 표현을 헷갈리는지, 어떤 구조를 잘 이해하는지 관찰하기

    • 교훈을 다음 스펙에 적극 반영

  • AI 에이전트 분야는 빠르게 진화하며 도구, 모범 사례가 등장하므로 계속해서 학습하고 반영해야함

• 개선 필요

  • 테스트 도입

  • 버전 관리 및 모니터링

    • 스펙 버전 관리하기

    • 로그 모니터링

  • 각종 도구 활용

    • AI에이전트 컨텍스트 관리 도구 활용하기

    • 에이전트 팩으로 서브에이전트 활용하기

    • 프레임워크 활용하여 전략적 모델 선정(효율적인 토큰 사용)

흔히 저지르는 실수

모호한 프롬프트

• 모호한 요청

  • 당신은 도움이 되는 코딩 어시스턴트입니다.

  • 이 프로젝트의 타입스크립트 더 좋게 개선해줘

• 구체적으로 명시하기(역할·범위·제약 지정)

  • 당신은 React 컴포넌트 테스트를 작성하는 테스트 엔지니어이며, 이 예시를 따르고 소스 코드는 절대 수정하지 않는다.

  • App.tsx의 13~20line의 type을 더 좁혀줘

요약 없는 과도한 컨텍스트

• 대량의 문서를 그대로 전달 > 알아서 하길 기대 > 대부분 실패

• 보완

  • 계층적 요약 제공

  • RAG활용

인간 검토 스킵

• Willison의 개인 원칙: “다른 사람에게 설명할 수 없는 코드는 커밋하지 않는다”

• AI 생성 코드 = 카드로 만든 집(무너질 수 있음)

• 정확하고 안전하며 유지보수 가능하다는 것을 검증해야함

• 중요한 코드는 사람이 직접 검토(이커머스라면 결제, 배송, 인증 과 같은 부분)

바이브 코딩과 프로덕션 엔지니어링 혼동

• 바이브 코딩

  • AI를 활용한 빠른 프로토타이핑

  • 탐색 단계나 일회성 프로젝트에 적합

• 프로덕션 엔지니어링

  • 엄격한 스펙, 테스트, 검토가 필수

  • 이 아티클에서 설명한 규율과 절차가 필요

• 어떤 모드로 작업중인지 스스로 인식해야함

치명적 삼중주

• 치명적 삼중주란? AI 에이전트를 위험하게 만드는 속성 세가지

  • 속도: 사람이 검토할 수 있는 속도보다 빠르게 생성

  • 비결정성: 같은 입력, 실행마다 다른 출력

  • 비용: 검증을 충분히 하지 않고 편법 유도

6가지 핵심 영역 누락

• 스펙이 6가지 핵심 영역을 다루지 않으면, 에이전트가 중요한 정보를 놓치기 쉬움

• 스펙을 넘기기 전에 한번 더 점검하기

결론

• 효과적인 스펙 작성을 위해서 필요한 것

  • 소프트웨어 엔지니어링 원칙 이해하기

  • LLM의 특성을 이해하고 이에 맞게 조정하기

• 목적을 또렷하게 하는 것에서 시작, AI가 계획과 세부를 확장하도록 역할 분담

• 스펙 = 메모❌, 설계 문서⭕️

  • 6가지 핵심 영역을 포함하고, 실행 가능한 아티팩트로 취급할 것

• 한번에 모든것 요청❌, 작업 단위별로 쪼개기⭕️(에이전트의 집중력 유지)

  • 방법: 요약 TOC, 서브에이전트, 병렬 오케스트레이션

• AI가 빠지기 쉬운 함정을 미리 차단하기

  • 방법: 3단계 경계(Always / Ask first / Never), 자가 검사, 적합성 테스트

• 스펙 & 구현된 코드 = 고정된 결과물❌, 반복 과정⭕️

  • 테스트와 피드백을 통해 스펙과 코드 둘다 수정해 나감