프로젝트 개발 방법론

프로젝트 개발 방법론은(는) 무엇을 하나요?

이 스킬은 LLM 처리에 적합한 작업을 식별하고, 효과적인 프로젝트 아키텍처를 설계하며, 에이전트 지원 개발을 사용하여 신속하게 반복하는 원리를 다룹니다. 이 방법론은 배치 처리 파이프라인, 다중 에이전트 연구 시스템 또는 대화형 에이전트 애플리케이션을 구축할 때 모두 적용됩니다.

이 스킬의 작업 단위는 전체 프로젝트 또는 다단계 파이프라인입니다. 개별 도구 설계(설명, 스키마, 오류 메시지)는 tool-design에 속합니다. 스킬별 활성화 라우팅은 해당 스킬과 코퍼스 인덱스에 속합니다. 이 스킬은 프로젝트 수준의 질문을 담당합니다: 이 작업을 LLM으로 구축해야 하는지, 파이프라인의 형태는 무엇인지, 비용은 얼마인지, 어떻게 반복할 것인지.

활성화 시점

작업 단위가 전체 프로젝트 또는 파이프라인일 때 이 스킬을 활성화하십시오:

• LLM이 작업에 적합한 원시 도구인지 결정(코드 작성 전 작업-모델 적합성).
• 다단계 배치 또는 에이전트 파이프라인 구성(획득 / 준비 / 처리 / 파싱 / 렌더링).
• LLM 중심 프로젝트의 토큰, 비용 및 일정 추정.
• 프로젝트 수준에서 단일 에이전트와 다중 에이전트 중 선택.
• 에이전트 지원 반복 구조화(에이전트가 프로젝트 자체를 구축하는 데 도움을 주는 경우).
• 파이프라인 계약 수준에서 구조화된 출력 설계(단계 간 핸드오프 형식).

다른 스킬이 담당하는 인접 작업에는 이 스킬을 활성화하지 마십시오:

• 도구별 설명, 스키마, 명명, 응답 형식, 오류 메시지: tool-design.
• 궤적별 토큰 효율성 전략(마스킹, 분할, 캐싱): context-optimization.
• 에이전트 토폴로지 수준에서 하위 에이전트로 작업 분할 결정: multi-agent-patterns.
• 자율 제어 루프 설계(고정 메트릭, 참신성 게이트, 인간 승인 경계): harness-engineering.

핵심 개념

작업-모델 적합성 인식

코드를 작성하기 전에 작업-모델 적합성을 평가하십시오. 근본적으로 부적합한 작업에 자동화를 구축하는 것은 며칠의 노력을 낭비하기 때문입니다. 제안된 모든 작업을 다음 두 표에 대입하여 진행 또는 중단을 결정하십시오.

작업에 다음과 같은 특성이 있으면 진행하십시오:

특성	근거
여러 출처의 종합	LLM은 규칙 기반 대안보다 여러 입력의 정보를 더 잘 결합합니다
루브릭이 있는 주관적 판단	채점, 평가, 기준이 있는 분류는 언어 추론에 자연스럽게 매핑됩니다
자연어 출력	목표가 사람이 읽을 수 있는 텍스트일 때 LLM이 기본적으로 제공합니다
오류 허용	개별 실패가 전체 시스템을 망가뜨리지 않으므로 LLM 비결정론이 허용됩니다
배치 처리	항목 간 대화 상태가 필요 없어 컨텍스트가 깔끔하게 유지됩니다
훈련 데이터의 도메인 지식	모델이 이미 관련 컨텍스트를 가지고 있어 프롬프트 엔지니어링 오버헤드가 줄어듭니다

작업에 다음과 같은 특성이 있으면 중단하십시오:

특성	근거
정밀한 계산	수학, 계산, 정확한 알고리즘은 언어 모델에서 신뢰할 수 없습니다
실시간 요구사항	LLM 지연 시간은 서브초 응답에 너무 높습니다
완벽한 정확도 요구사항	환각 위험으로 100% 정확도는 불가능합니다
독점 데이터 의존성	모델에 필요한 컨텍스트가 없으며 프롬프트만으로 획득할 수 없습니다
순차적 의존성	각 단계가 이전 결과에 크게 의존하여 오류가 누적됩니다
결정론적 출력 요구사항	동일 입력이 동일 출력을 생성해야 하며, LLM이 보장할 수 없습니다

수동 프로토타입 단계

자동화에 투자하기 전에 항상 수동 테스트로 작업-모델 적합성을 검증하십시오. 대표 입력 하나를 모델 인터페이스에 복사하고, 출력 품질을 평가한 후, 다음 질문에 답하는 데 결과를 사용하십시오:

• 모델이 이 작업에 필요한 지식을 가지고 있습니까?
• 모델이 필요한 형식으로 출력을 생성할 수 있습니까?
• 대규모에서 기대할 수 있는 품질 수준은 무엇입니까?
• 해결해야 할 명백한 실패 모드가 있습니까?

이렇게 하는 이유는 실패한 수동 프로토타입이 실패한 자동화 시스템을 예측하는 반면, 성공한 프로토타입은 품질 기준과 프롬프트 디자인 템플릿을 모두 제공하기 때문입니다. 이 테스트는 몇 분이면 끝나며 수 시간의 낭비되는 개발을 방지합니다.

파이프라인 아키텍처

LLM 프로젝트를 단계별 파이프라인으로 구성하십시오. 결정론적 단계와 비결정론적 단계를 분리하면 빠른 반복과 비용 제어가 가능하기 때문입니다. 각 단계를 다음과 같이 설계하십시오:

• 분리됨: 단계 간 명확한 경계로 각각을 독립적으로 디버깅 가능
• 멱등성: 재실행 시 동일한 결과를 생성하여 중복 작업 방지
• 캐시 가능: 중간 결과를 디스크에 유지하여 값비싼 재계산 방지
• 독립적: 각 단계를 별도로 실행할 수 있어 선택적 재실행 가능

이 표준 파이프라인 구조를 사용하십시오:

획득 -> 준비 -> 처리 -> 파싱 -> 렌더링

1. 획득: 소스(API, 파일, 데이터베이스)에서 원시 데이터 가져오기
2. 준비: 데이터를 프롬프트 형식으로 변환
3. 처리: LLM 호출 실행(비싸고 비결정론적인 단계)
4. 파싱: LLM 출력에서 구조화된 데이터 추출
5. 렌더링: 최종 출력 생성(보고서, 파일, 시각화)

1, 2, 4, 5단계는 결정론적입니다. 3단계는 비결정론적이고 비용이 많이 듭니다. 이 분리를 유지하면 필요한 경우에만 값비싼 LLM 단계를 재실행하면서 파싱과 렌더링을 빠르게 반복할 수 있습니다.

파일 시스템을 상태 머신으로 사용

데이터베이스나 메모리 내 구조 대신 파일 시스템을 사용하여 파이프라인 상태를 추적하십시오. 파일 존재가 자연스러운 멱등성과 사람이 읽을 수 있는 디버깅을 제공하기 때문입니다.

data/{id}/
  raw.json         # 획득 단계 완료
  prompt.md        # 준비 단계 완료
  response.md      # 처리 단계 완료
  parsed.json      # 파싱 단계 완료

항목이 처리되어야 하는지 출력 파일 존재 여부로 확인하십시오. 출력 파일과 다운스트림 파일을 삭제하여 단계를 재실행하십시오. 중간 파일을 직접 읽어 디버깅하십시오. 이 패턴은 각 디렉토리가 독립적이어서 간단한 병렬화와 쉬운 캐싱을 가능하게 하기 때문에 작동합니다.

구조화된 출력 설계

구조화된 파싱 가능한 출력을 위한 프롬프트를 설계하십시오. 프롬프트 설계가 파싱 신뢰성을 직접 결정하기 때문입니다. 모든 구조화된 프롬프트에 다음 요소를 포함하십시오:

1. 섹션 마커: 파서가 매칭할 수 있는 명시적 헤더 또는 접두사
2. 형식 예제: 출력이 어떻게 보여야 하는지 정확히 표시
3. 근거 공개: "이것을 프로그래밍 방식으로 파싱할 것입니다"라고 명시하여 모델이 형식 준수를 우선시하도록 함
4. 제한된 값: 열거된 옵션, 점수 범위, 고정된 형식

LLM이 지침을 완벽하게 따르지 않으므로 LLM 출력 변형을 우아하게 처리하는 파서를 구축하십시오. 사소한 형식 변형에 유연한 정규식 패턴을 사용하고, 섹션이 누락된 경우 합리적인 기본값을 제공하며, 충돌 대신 검토를 위해 파싱 실패를 기록하십시오.

에이전트 지원 개발

에이전트 지원 모델을 사용하여 빠른 반복을 통해 개발을 가속화하십시오: 프로젝트 목표와 제약 조건을 설명하고, 에이전트가 초기 구현을 생성하도록 한 후, 특정 실패를 테스트하고 반복하며, 결과에 따라 프롬프트와 아키텍처를 개선하십시오.

에이전트 출력을 집중적이고 고품질로 유지하기 위해 다음 관행을 채택하십시오:

• 수정 주기를 줄이기 위해 사전에 명확하고 구체적인 요구사항 제공
• 대규모 프로젝트를 개별 구성 요소로 나누어 각각을 독립적으로 검증
• 조기 실패 포착을 위해 다음 단계로 넘어가기 전에 각 구성 요소 테스트
• 컨텍스트 저하를 방지하기 위해 에이전트를 한 번에 하나의 작업에 집중

비용 및 규모 추정

시작하기 전에 LLM 처리 비용을 추정하십시오. 토큰 비용은 대규모에서 빠르게 누적되며, 예산 초과를 늦게 발견하면 값비싼 재작업이 필요하기 때문입니다. 다음 공식을 사용하십시오:

총 비용 = (항목 수 x 항목당 토큰 수 x 토큰당 가격) + API 오버헤드

배치 처리의 경우 항목당 입력 토큰(프롬프트 + 컨텍스트)을 추정하고, 항목당 출력 토큰(일반적인 응답 길이)을 추정한 후, 항목 수를 곱하고 재시도 및 실패에 대해 20-30% 버퍼를 추가하십시오.

개발 중에 실제 비용을 추적하십시오. 비용이 추정치를 크게 초과하면 잘림을 통해 컨텍스트 길이를 줄이거나, 간단한 항목에 더 작은 모델을 사용하거나, 부분 결과를 캐싱 및 재사용하거나, 병렬 처리를 추가하여 벽시계 시간을 줄이십시오.

상세 주제

단일 vs 다중 에이전트 아키텍처 선택

독립적인 항목이 있는 배치 처리의 경우 기본적으로 단일 에이전트 파이프라인을 선택하십시오. 관리가 더 간단하고, 실행 비용이 저렴하며, 디버깅이 쉽기 때문입니다. 다음 조건 중 하나가 충족될 때만 다중 에이전트 아키텍처로 전환하십시오:

• 서로 다른 측면의 병렬 탐색이 필요한 경우
• 작업이 단일 컨텍스트 창 용량을 초과하는 경우
• 전문화된 하위 에이전트가 벤치마크에서 품질을 입증 가능하게 향상시키는 경우

역할 의인화가 아닌 컨텍스트 분리를 위해 다중 에이전트를 선택하십시오. 하위 에이전트는 집중된 하위 작업을 위해 새로운 컨텍스트 창을 얻어 장기 실행 작업에서 컨텍스트 저하를 방지합니다.

자세한 아키텍처 지침은 multi-agent-patterns 스킬을 참조하십시오.

아키텍처 축소

최소한의 아키텍처로 시작하고 생산 증거가 필요함을 입증할 때만 복잡성을 추가하십시오. 과도하게 설계된 스캐폴딩은 종종 모델 성능을 제약하기보다는 제한하기 때문입니다.

Vercel d0 사례 연구는 많은 전문화된 도구를 명령 실행과 SQL이라는 두 가지 프리미티브로 축소한 후 성공이 개선되었다고 보고합니다(claim-project-development-vercel-d0-reduction). 파일 시스템 에이전트 패턴은 맞춤형 탐색 도구 대신 표준 Unix 유틸리티를 사용합니다.

다음과 같은 경우 축소하십시오:

• 데이터 계층이 잘 문서화되고 일관되게 구조화된 경우
• 모델이 충분한 추론 능력을 가진 경우
• 전문화된 도구가 가능하게 하기보다는 제약하는 경우
• 결과 개선보다 스캐폴딩 유지 관리에 더 많은 시간을 소비하는 경우

다음과 같은 경우 복잡성을 추가하십시오:

• 기본 데이터가 지저분하거나, 일관성이 없거나, 제대로 문서화되지 않은 경우
• 도메인이 모델이缺乏하는 전문화된 지식을 요구하는 경우
• 안전 제약 조건이 에이전트 기능을 제한해야 하는 경우
• 작업이 진정으로 복잡하고 구조화된 워크플로의 이점을 얻는 경우

자세한 도구 아키텍처 지침은 tool-design 스킬을 참조하십시오.

반복 및 리팩토링

처음부터 여러 번의 아키텍처 반복을 계획하십시오. 대규모 생산 에이전트 시스템은 항상 리팩토링이 필요하기 때문입니다. Manus는 출시 이후 에이전트 프레임워크를 다섯 번 리팩토링했습니다. Bitter Lesson은 현재 모델 제한 사항을 위해 추가된 구조가 모델이 개선됨에 따라 제약 조건이 된다고 제안합니다.

변화를 위해 구축하려면 다음 관행을 따르십시오:

• 리팩토링이 저렴하도록 아키텍처를 단순하고 의견에 얽매이지 않게 유지
• 모델 세대를 걸쳐 테스트하여 하네스가 성능을 제한하지 않는지 확인
• 제한 사항을 고정하기보다는 모델 개선의 혜택을 받는 시스템 설계

실용 지침

프로젝트 계획 템플릿

각 단계가 다음 단계가 노력을 투자하기 전에 가정을 검증하므로 이 템플릿을 순서대로 따르십시오.

1. 작업 분석

   • 입력과 원하는 출력을 명시적으로 정의
   • 분류: 종합, 생성, 분류 또는 분석
   • 비즈니스 영향을 기반으로 허용 가능한 오류율 설정
   • 비용을 정당화하기 위해 성공적인 완료당 가치 추정

2. 수동 검증

   • 대상 모델로 대표 예제 하나 테스트
   • 요구사항에 대한 출력 품질 및 형식 평가
   • 파서 강화 또는 프롬프트 수정이 필요한 실패 모드 식별
   • 비용 예측을 위한 항목당 토큰 추정

3. 아키텍처 선택

   • 위 기준에 따라 단일 파이프라인 대 다중 에이전트 선택
   • 필요한 도구 및 데이터 소스 식별
   • 파일 시스템 상태를 사용한 저장소 및 캐싱 전략 설계
   • 처리 단계를 위한 병렬화 접근 방식 계획

4. 비용 추정

   • 20-30% 버퍼로 항목 x 토큰 x 가격 계산
   • 각 파이프라인 단계의 개발 시간 추정
   • 인프라 요구사항 식별(API 키, 저장소, 컴퓨팅)
   • 생산 실행을 위한 지속적인 운영 비용 예측

5. 개발 계획

   • 각 단계를 진행하기 전에 테스트하면서 단계별로 구현
   • 예상 출력과 함께 단계별 테스트 전략 정의
   • 품질 메트릭에 연결된 반복 이정표 설정
   • 롤백 기능을 갖춘 배포 접근 방식 계획

예제

예제 1: 배치 분석 파이프라인 (Karpathy의 HN Time Capsule)

작업: 10년 전의 930개 HN 토론을 회고 등급으로 분석.

아키텍처:

• 5단계 파이프라인: 가져오기 -> 프롬프트 -> 분석 -> 파싱 -> 렌더링
• 파일 시스템 상태: data/{date}/{item_id}/ 단계 출력 파일 포함
• 구조화된 출력: 명시적 형식 요구사항이 있는 6개 섹션
• 병렬 실행: LLM 호출에 15개 워커

결과: 총 비용 $58, 약 1시간 실행, 정적 HTML 출력.

예제 2: 아키텍처 축소 (Vercel d0)

작업: 내부 분석을 위한 Text-to-SQL 에이전트.

이전: 많은 전문화된 도구, 낮은 측정 성공률, 긴 평균 실행 시간.

이후: 두 가지 도구(bash + SQL), 높은 측정 성공률, 짧은 평균 실행 시간(claim-project-development-vercel-d0-reduction).

핵심 통찰: 의미 계층이 이미 좋은 문서였다. Claude는 파일을 직접 읽을 수 있는 접근 권한만 있으면 되었다.

자세한 분석은 사례 연구를 참조하십시오.

지침

1. 자동화를 구축하기 전에 수동 프로토타이핑으로 작업-모델 적합성 검증
2. 파이프라인을 분리되고, 멱등적이며, 캐시 가능한 단계로 구성
3. 상태 관리 및 디버깅에 파일 시스템 사용
4. 명시적 형식 예제와 함께 구조화되고 파싱 가능한 출력을 위한 프롬프트 설계
5. 최소 아키텍처로 시작하고 필요할 때만 복잡성 추가
6. 초기에 비용을 추정하고 개발 전반에 걸쳐 추적
7. LLM 출력 변형을 처리하는 강력한 파서 구축