Skip to content

위임 가능한 작업의 해부학: AI 에이전트를 위한 구조화된 정의

위임 가능한 작업의 해부학: AI 에이전트를 위한 구조화된 정의
Share
   

왜 어떤 위임된 작업은 완벽하게 돌아오고 다른 것은 세 번의 명확화가 필요한가?

차이는 AI의 능력이 아니다—작업 정의다. 모호한 지시는 모호한 결과를 낳는다. 구조화된 정의는 자율 실행을 낳는다.

플랜 에이전트가 일관되게 위임 가능한 작업을 생성하는 것을 보고, 템플릿을 추출했다. 모든 섹션은 그것의 부재가 문제를 일으키기 때문에 존재한다.

WHY: 모호함은 비싸다

“로그인 기능 구현해"로 AI 에이전트에게 작업을 위임하면, 얻는 것:

  • 범위에 대한 질문 (“비밀번호 재설정 포함하나요?”)
  • 패턴에 대한 잘못된 가정 (“JWT를 썼어요 왜냐면…”)
  • 누락된 엣지 케이스 (“레이트 리미팅 안 넣었어요 왜냐면…”)
  • 검증 불가능한 완료 (“이제 작동해야 해요”)

각 명확화 라운드는 시간이 든다. 각 잘못된 가정은 재작업이 든다. 작업 구조에 대한 선행 투자가 줄어든 반복으로 스스로 지불된다.

HOW: 템플릿

완전한 작업 정의는 일곱 섹션이 있다:

### 작업 N: [설명적 이름]

**할 것**:
- 코드 예제가 있는 구체적 액션
- 파일 경로가 있는 예상 변경
- 사용할 기술적 접근법

**하지 말 것**:
- 명시적 가드레일
- 금지된 패턴
- 범위 경계

**권장 에이전트 프로필**:
- **카테고리**: `quick|visual-engineering|ultrabrain|deep|writing`
- **스킬**: [`skill-1`, `skill-2`]
- **평가했으나 생략한 스킬**: [이유와 함께]

**병렬화**:
- **병렬 실행 가능**: 예/아니오
- **병렬 그룹**: 웨이브 N
- **차단**: 작업 X, Y
- **차단됨**: 작업 A, B

**참조**:
- `path/to/file.ts:42-60` - 구체적 라인
- 외부 문서 링크
- 각 참조가 왜 중요한지

**수락 기준**:
```bash
# 에이전트가 검증 위해 실행할 수 있는 명령
grep -q "expected_pattern" file.ts && echo "PASS"
npm test -- --grep "feature"

커밋: 예/아니오

  • 메시지 포맷
  • 포함할 파일

### 각 섹션이 중요한 이유

**할 것**: 범위에 대한 모호함 제거. "로그인 구현" vs "users 테이블에 대해 email/password를 검증하고 24시간 만료의 JWT를 반환하는 POST /api/login 엔드포인트 추가"는 다른 수준의 명세다.

**하지 말 것**: 범위 크리프와 로그 동작 방지. 에이전트는 완료를 최적화한다—제약하지 않으면 요청하지 않은 기능을 추가할 것이다. "비밀번호 재설정 플로우 추가하지 마"는 명시적이다.

**카테고리 + 스킬**: 올바른 능력으로 라우팅. UI 작업이 백엔드 특화 에이전트에 가면 안 된다. 스킬이 도메인 지식을 주입한다.

**병렬화**: 동시 실행을 가능하게 한다. 의존성 정보 없이는 작업이 순차로 실행되어야 한다. 있으면 독립 작업이 병렬화할 수 있다.

**참조**: 재탐색 없이 맥락 제공. "auth가 다른 곳에서 어떻게 되는지 봐" 대신, 정확한 파일과 라인 제공. 에이전트가 검색에 시간 낭비 안 함.

**수락 기준**: 완료를 검증 가능하게 만든다. "작동해야 해" vs "`npm test auth` 실행이 통과"는 "날 믿어"와 "증명해"의 차이다.

**커밋**: 출력 기대 명세. 에이전트가 커밋해야 하나? 어떤 메시지로? 어떤 파일이 포함되어야 하나?

## WHAT: 예시

### 나쁜 작업 정의

작업: 사용자 인증 추가

할 것: 로그인과 가입 구현 참조: 기존 auth 코드 봐


문제:
- 기술적 접근법 명시 없음
- 범위 경계 없음
- "봐"는 탐색 필요
- 검증 기준 없음

### 좋은 작업 정의
```markdown
### 작업 3: 로그인 엔드포인트 추가

**할 것**:
- `src/routes/auth.ts`에 `POST /api/auth/login` 생성
- 요청 바디 검증: `{ email: string, password: string }`
- Prisma를 통해 `users` 테이블에 대해 자격 증명 확인
- 기존 `signToken()` 헬퍼를 사용해 24시간 만료 JWT 반환
- 유효하지 않은 자격 증명에 "Invalid email or password" 메시지와 함께 401 반환

**하지 말 것**:
- 가입 엔드포인트 추가 안 함 (작업 4)
- 비밀번호 재설정 추가 안 함
- 기존 auth 미들웨어 수정 안 함
- 레이트 리미팅 추가 안 함 (별도 작업)

**권장 에이전트 프로필**:
- **카테고리**: `quick`
- **스킬**: [`typescript-programmer`]

**병렬화**:
- **병렬 실행 가능**: 아니오
- **차단됨**: 작업 2 (데이터베이스 스키마)

**참조**:
- `src/routes/auth.ts:1-30` - 기존 auth 구조
- `src/utils/jwt.ts:15-25` - signToken 헬퍼
- `prisma/schema.prisma:42-50` - User 모델
- 왜: 매치할 기존 패턴 보여줌

**수락 기준**:
```bash
# 엔드포인트 존재
grep -q "router.post('/login'" src/routes/auth.ts

# 유효한 자격 증명에 JWT 반환
curl -X POST localhost:3000/api/auth/login \
  -d '{"email":"test@test.com","password":"test"}' \
  | jq -e '.token'

# 유효하지 않은 자격 증명에 401 반환
curl -s -o /dev/null -w "%{http_code}" \
  -X POST localhost:3000/api/auth/login \
  -d '{"email":"wrong","password":"wrong"}' | grep -q "401"

커밋: 예

  • 메시지: feat(auth): add login endpoint
  • 파일: src/routes/auth.ts

이 작업은 위임되어 자율적으로 실행될 수 있다. 에이전트는 무엇을 해야 하는지, 하지 말아야 하는지, 어디를 봐야 하는지, 완료를 어떻게 검증하는지 정확히 안다.

## 요약

템플릿의 모든 섹션은 그것 없이 작업이 실패하는 것을 봤기 때문에 존재한다:
- "할 것" 누락 → 잘못된 범위
- "하지 말 것" 누락 → 범위 크리프
- 참조 누락 → 낭비된 탐색
- 수락 기준 누락 → 검증 불가능한 완료

작업 구조에 시간 투자는 생각을 선행 로드한다. 에이전트가 실행한다; 당신은 베이비시팅 안 한다.

5분 걸려 쓰는 작업 정의가 30분의 명확화와 재작업을 아낀다. 5분의 구조가 30분의 왔다갔다를 이긴다.