TIL - 20260909

juni·2026년 9월 9일

목록 보기

452/468

0909 운영 자동화/AI 워크플로우 심화 (5/N): 개발 작업 오케스트레이션과 AI 작업 단위 관리

✅ 1. 개발 작업 오케스트레이션이란 무엇인가?

개발 작업 오케스트레이션은 여러 개발 단계를 하나의 흐름으로 연결하는 것입니다.
단순히 Codex에게 코드를 작성시키는 것이 아니라, 작업 정의부터 검증, 기록까지 같은 기준으로 관리하는 것이 핵심입니다.
AI 개발 도구를 많이 사용할수록 “무엇을 맡겼고, 어디까지 성공했고, 무엇을 사람이 확인해야 하는가”가 명확해야 합니다.

요구사항
  ↓
작업 정의
  ↓
Issue 생성
  ↓
Branch 생성
  ↓
Codex 작업
  ↓
자동 QA
  ↓
사람 검토
  ↓
Commit
  ↓
배포 후보
  ↓
작업 보고서

➕ 1-1. 단순 AI 코딩과의 차이

단순 AI 코딩:
프롬프트 입력
  ↓
코드 수정
  ↓
끝

오케스트레이션:
작업 정의
  ↓
변경 범위 제한
  ↓
코드 수정
  ↓
테스트
  ↓
위험도 분석
  ↓
리뷰
  ↓
기록

AI가 실제 개발 워크플로우 안에 들어오려면 코드 생성보다 작업 관리가 더 중요합니다.

✅ 2. 왜 작업 단위 관리가 중요한가?

AI/Codex에게 여러 기능을 한 번에 맡기면 변경 범위가 커지고 검토하기 어려워집니다.
특히 1인 개발자는 리뷰어가 따로 없기 때문에 작업을 작게 나누는 것이 중요합니다.

➕ 2-1. 나쁜 작업 단위

관리자 시스템 전체 리팩토링해줘.

문제:

수정 범위가 너무 큼
기존 기능 영향 파악 어려움
테스트 범위가 불명확
Rollback 어려움
Commit 의미가 흐려짐
AI가 필요 이상의 파일을 수정할 수 있음

➕ 2-2. 좋은 작업 단위

상담 상태 변경 API에서
상태 변경 + 상태 이력 + Audit Log를
하나의 transaction으로 묶어줘.

범위:
consult/application/update-consult-status
consult.repository.ts
audit-log.repository.ts

제외:
프론트
상품
Notification
DB schema 변경

작업 단위가 작을수록 AI 결과를 신뢰하기 쉬워집니다.
Git commit과 트러블슈팅 기록도 깔끔해집니다.

✅ 3. 작업 단위의 기본 구조

AI에게 작업을 맡길 때는 최소한 아래 정보가 있어야 합니다.

목적
현재 문제
작업 범위
제외 범위
완료 조건
테스트 조건
보안 조건
금지 사항

➕ 3-1. Task Spec 예시

# Task: 상담 상태 변경 Transaction 정리

## 목적
상담 상태 변경 시 상태 이력과 Audit Log 누락 가능성을 줄인다.

## 현재 문제
상태 변경과 상태 이력 저장이 서로 다른 흐름에서 실행되고 있다.

## 수정 범위
- update-consult-status.use-case.ts
- consult.repository.ts
- audit-log.repository.ts

## 수정 제외
- frontend
- product module
- notification module
- Prisma schema

## 완료 조건
- 상태 변경, history, Audit Log가 같은 transaction
- 하나라도 실패하면 전체 rollback
- 기존 API 응답 구조 유지
- 동시성 충돌은 기존 409 유지

## 테스트
- 정상 상태 변경
- 잘못된 상태 전이
- Audit Log 실패 rollback

## 보안
- phoneNormalized 응답 금지
- 고객 전화번호 로그 금지

이 문서 자체를 AI 작업 입력으로 사용할 수 있습니다.

✅ 4. Issue를 작업의 기준점으로 사용하기

GitHub Issue나 로컬 Task 파일을 작업의 기준점으로 두면 좋습니다.
Issue 하나를 하나의 실질적인 변경 단위로 보는 방식입니다.

Issue #142
  ↓
Branch
  ↓
Commits
  ↓
QA Report
  ↓
Troubleshooting
  ↓
Daily Report

➕ 4-1. Issue에 넣을 항목

제목
문제 상황
목표
작업 범위
완료 조건
테스트 항목
위험도
관련 화면/API
관련 문서

➕ 4-2. 예시

# [Backend] 상담 상태 변경 Transaction 정리

## 문제
상태 변경, history, Audit Log 저장 흐름이 분리되어 있음

## 목표
3개 작업을 하나의 transaction으로 처리

## 완료 조건
- 성공 시 모두 반영
- 실패 시 모두 rollback
- 기존 응답 유지
- 동시성 409 유지

## QA
- NEW → CALLING
- invalid transition
- concurrent update
- Audit Log rollback

Issue가 있으면 AI에게 맥락을 다시 설명하는 비용도 줄어듭니다.

✅ 5. Issue 크기 기준

➕ 5-1. 너무 작은 Issue

버튼 padding 4px 수정
텍스트 오타 수정

이런 작업은 별도 Issue 없이 commit으로 충분할 수 있습니다.

➕ 5-2. 적절한 Issue

상담 상태 변경 transaction 정리
관리자 Excel ExportJob 도입
PermissionGuard 적용
Webhook signature 검증 추가

➕ 5-3. 너무 큰 Issue

백엔드 전체 아키텍처 개선
관리자 시스템 전면 개편
3사 통신사 전체 확장

➕ 5-4. 판단 기준

한 가지 목표가 있는가?
한 번에 리뷰 가능한가?
독립적으로 테스트 가능한가?
독립적으로 commit 가능한가?
문제가 생기면 부분 rollback 가능한가?

하나라도 “아니오”가 많으면 작업을 더 나누는 것이 좋습니다.

✅ 6. Branch 자동 생성

Issue 번호와 작업 유형을 branch 이름에 포함하면 추적이 쉬워집니다.

feature/142-consult-status-transaction
fix/153-export-expired-file
refactor/161-consult-repository
test/168-permission-e2e

➕ 6-1. 패턴

<type>/<issue-number>-<short-description>

➕ 6-2. type 후보

feature
fix
refactor
test
docs
chore
hotfix

➕ 6-3. CLI 예시

llm-work start 142

내부:

Issue #142 조회
  ↓
작업 유형 확인
  ↓
branch 이름 생성
  ↓
git switch -c

브랜치 이름만 봐도 어떤 Issue 작업인지 알 수 있게 만드는 것이 좋습니다.

✅ 7. 작업 시작 전 Working Tree 확인

AI 작업 시작 전 기존 미커밋 변경이 있는지 확인해야 합니다.
기존 작업과 AI 작업이 섞이면 diff 검토가 어려워집니다.

git status --short

➕ 7-1. 깨끗한 경우

Working tree clean
→ 작업 진행

➕ 7-2. 변경사항이 있는 경우

기존 변경사항이 있습니다.

M src/...
?? ...

AI 작업과 섞일 수 있으므로
현재 변경사항을 먼저 처리하세요.

➕ 7-3. 자동화 기준

기본:
dirty working tree면 경고

안전 모드:
작업 시작 차단

옵션:
--allow-dirty

특히 Codex 작업은 예상보다 많은 파일을 수정할 수 있으므로 시작 상태를 깨끗하게 하는 것이 좋습니다.

✅ 8. Before Snapshot

AI 작업 전 상태를 기록하면 작업 후 변경 범위를 비교하기 좋습니다.

branch
HEAD commit
working tree
현재 테스트 상태
관련 파일 목록

➕ 8-1. 예시

{
  "branch": "feature/142-consult-status-transaction",
  "baseCommit": "abc123",
  "workingTree": "clean",
  "taskId": 142
}

➕ 8-2. 활용

작업 전 snapshot
  ↓
Codex 수정
  ↓
git diff
  ↓
예상 범위와 비교

Before Snapshot은 AI가 작업 목적과 관계없는 파일을 수정했는지 찾는 기준이 됩니다.

✅ 9. AI 작업 프롬프트 자동 생성

Task Spec이 있으면 Codex용 프롬프트를 자동으로 만들 수 있습니다.

Issue
  ↓
Task Spec
  ↓
Prompt Builder
  ↓
Codex Prompt

➕ 9-1. 자동 포함할 내용

작업 목적
현재 문제
수정 허용 파일
수정 금지 영역
아키텍처 규칙
보안 규칙
완료 조건
테스트 조건
결과 보고 형식

➕ 9-2. 기본 아키텍처 규칙

Controller에 비즈니스 로직 넣지 않기
transaction은 Use Case에서 관리
Prisma query는 Repository에 두기
외부 API는 Adapter/Worker 사용
표준 error response 유지
민감정보 로그 금지

매번 같은 규칙을 직접 입력하기보다 공통 프롬프트 템플릿에 넣는 것이 좋습니다.

✅ 10. 프로젝트 규칙 파일

AI에게 매번 설명하는 공통 기준은 프로젝트 문서로 관리하면 좋습니다.

docs/ai/
  coding-rules.md
  backend-rules.md
  frontend-rules.md
  security-rules.md
  testing-rules.md

➕ 10-1. `backend-rules.md`

Controller는 HTTP 역할만 담당
Use Case가 transaction boundary 관리
Repository에서 Prisma 접근
중요 변경은 Audit Log 기록
외부 API는 transaction 밖에서 실행

➕ 10-2. `security-rules.md`

고객 전화번호 로그 금지
Secret 하드코딩 금지
운영 DB 직접 수정 금지
.env 수정 금지
PII 응답 DTO 검토

➕ 10-3. 장점

AI 프롬프트 길이 감소
규칙 일관성 유지
Codex 작업마다 같은 기준 적용
문서 자체가 개발 가이드 역할

AI 시대에는 프로젝트 문서가 사람뿐 아니라 AI를 위한 개발 규칙이 되기도 합니다.

✅ 11. 작업 범위 제한

AI 작업에서 가장 중요한 안전장치 중 하나입니다.

➕ 11-1. Allowlist

수정 허용:
src/modules/consult/**
src/modules/audit-log/**

➕ 11-2. Denylist

수정 금지:
prisma/schema.prisma
prisma/migrations/**
deployment/**
.env*

➕ 11-3. 작업 후 확인

git diff --name-only
  ↓
allowlist 밖 변경 확인

➕ 11-4. 결과

허용 범위:
4개 파일

범위 밖:
src/modules/product/product.service.ts

→ WARNING

AI가 범위 밖 파일을 수정했다고 무조건 잘못된 것은 아니지만 반드시 사람이 확인해야 합니다.

✅ 12. 변경 범위 정책

STRICT:
허용 파일 밖 변경 → BLOCK

NORMAL:
허용 범위 밖 변경 → WARNING

OPEN:
범위 제한 없음

➕ 12-1. 추천

DB/권한/보안:
STRICT

일반 백엔드 기능:
NORMAL

대규모 리팩토링:
OPEN + 수동 리뷰

작업 성격에 따라 제한 수준을 다르게 두는 것이 현실적입니다.

✅ 13. Codex 작업 완료 후 받아야 할 결과

코드 수정만 받고 끝내면 안 됩니다.
변경 요약과 검증 결과도 받아야 합니다.

변경 파일
핵심 변경사항
테스트 실행 결과
실행하지 못한 테스트
주의사항
추가 TODO

➕ 13-1. 예시

## 변경 파일
- update-consult-status.use-case.ts
- consult.repository.ts
- audit-log.repository.ts

## 변경사항
- Use Case에서 Prisma transaction 시작
- 동일 tx를 Repository에 전달
- 상태 변경/history/audit 원자성 확보

## 테스트
- typecheck PASS
- consult unit PASS
- integration NOT RUN

## 주의
- 실제 DB 기반 rollback 테스트 필요

“테스트 못 돌렸다”는 정보도 중요합니다.

✅ 14. 완료 조건 자동 검증

Task Spec의 완료 조건을 체크리스트로 변환할 수 있습니다.

완료 조건:
[ ] 상태/history/audit 같은 transaction
[ ] 기존 API response 유지
[ ] 409 충돌 유지
[ ] phoneNormalized 응답 없음

➕ 14-1. 자동 확인 가능한 것

typecheck
test
응답 snapshot
변경 파일
금지 문자열

➕ 14-2. 사람이 확인해야 하는 것

업무 요구사항 적합성
실제 관리자 UX
아키텍처 적합성
운영 위험

완료 조건을 명문화하면 “코드는 돌아가는데 요구사항은 틀린” 상황을 줄일 수 있습니다.

✅ 15. 0908 QA 파이프라인 연결

Codex 작업 완료
  ↓
llm-report qa --staged
  ↓
Static Check
  ↓
Tests
  ↓
Risk Detection
  ↓
AI Review

➕ 15-1. 성공

PASS
→ commit 후보

➕ 15-2. 경고

PASS_WITH_WARNINGS
→ 사람 검토

➕ 15-3. 실패

BLOCK
→ 수정 후 QA 재실행

0908에서 만든 QA 흐름을 이번 오케스트레이션의 검증 단계로 사용하는 구조입니다.

✅ 16. 실패 유형 분류

AI 작업이 실패했을 때 이유를 분류하면 재작업을 자동화하기 쉽습니다.

TYPE_ERROR
LINT_ERROR
UNIT_TEST_FAILED
INTEGRATION_TEST_FAILED
SCOPE_VIOLATION
SECRET_DETECTED
REQUIREMENT_MISMATCH
UNKNOWN

➕ 16-1. 자동 수정 가능한 실패

TYPE_ERROR
LINT_ERROR
일부 명확한 UNIT_TEST_FAILED

➕ 16-2. 사람 검토가 필요한 실패

SCOPE_VIOLATION
REQUIREMENT_MISMATCH
DB migration 문제
권한 정책 문제
보안 문제

실패 유형별로 다음 행동이 달라져야 합니다.

✅ 17. 제한적 자동 재작업

QA 실패
  ↓
실패 유형 분류
  ↓
자동 수정 허용?
  ├─ Yes → Codex 재요청
  └─ No → 사람 검토

➕ 17-1. 재작업 프롬프트

이전 작업 결과에서 typecheck가 실패했습니다.

원래 요구사항과 수정 범위는 유지하고,
아래 오류만 해결해줘.

오류:
...

조건:
- 새 기능 추가 금지
- 수정 범위 확대 금지
- DB schema 변경 금지
- 완료 후 typecheck 실행

➕ 17-2. 최대 횟수

AUTO_RETRY_LIMIT=2

반복 횟수를 제한해야 AI가 계속 코드를 흔드는 것을 막을 수 있습니다.

✅ 18. Requirement Mismatch

테스트가 모두 통과해도 요구사항을 잘못 구현할 수 있습니다.
그래서 기능 요구사항 검토가 필요합니다.

➕ 18-1. 예시

요구:
STAFF는 상담 조회만 가능

구현:
STAFF도 상태 변경 가능

Typecheck:
PASS

Test:
기존 테스트 기준으로 PASS

하지만:
요구사항 불일치

➕ 18-2. 대응

Task Spec 완료 조건
  ↓
AI Review
  ↓
사람 기능 검토

테스트는 정의된 것을 검증할 뿐, 요구사항 자체가 맞는지는 보장하지 않습니다.

✅ 19. 사람 승인 Gate

운영 코드에서는 완전 자동 반영보다 승인 지점을 두는 것이 안전합니다.

Codex
  ↓
QA
  ↓
AI Review
  ↓
Human Approval
  ↓
Commit / Push

➕ 19-1. 승인 시 확인

변경 목적과 일치하는가?
불필요한 파일 변경이 없는가?
QA 결과가 정상인가?
DB/권한/보안 변경이 있는가?
배포 영향이 이해되는가?

사람 승인 단계는 완전히 없애는 것이 목표가 아닙니다.
사람이 봐야 할 양을 줄이는 것이 자동화의 목표입니다.

✅ 20. Commit 자동 생성

검토가 끝난 뒤 변경사항을 기반으로 commit message 후보를 자동 생성할 수 있습니다.

➕ 20-1. 입력

Task title
Issue number
변경 파일
Git diff summary

➕ 20-2. 출력

refactor(consult): 상태 변경 transaction 경계 정리 (#142)

➕ 20-3. 본문 예시

- 상담 상태 변경/history/audit를 하나의 transaction으로 처리
- 기존 상태 전이와 409 충돌 동작 유지
- rollback integration test 추가

자동 생성 후 사람이 확인하고 commit하는 방식이 좋습니다.

✅ 21. Commit과 Issue 연결

refactor(consult): 상태 변경 transaction 경계 정리 (#142)

또는 commit body:

Refs #142

➕ 21-1. 장점

커밋 → 요구사항 확인 가능
Issue → 실제 코드 변경 확인 가능
Daily Report → Issue 연결 가능

나중에 과거 변경 이유를 찾는 시간이 크게 줄어듭니다.

✅ 22. Push 전 최종 검사

git diff main...HEAD
  ↓
전체 branch 변경 검토

➕ 22-1. 왜 staged diff만으로 부족한가?

여러 commit이 존재할 수 있음
중간 수정이 누적됨
최종 branch 상태가 중요함

➕ 22-2. Push 전 확인

Branch 전체 변경 파일
전체 테스트
API contract
DB migration
Secret
Task 완료 조건

commit 단위 검토와 branch 전체 검토는 별도로 보는 것이 좋습니다.

✅ 23. 작업 완료 Report

작업이 끝나면 자동으로 작업 결과 문서를 만들 수 있습니다.

# Task Report: #142 상담 상태 변경 Transaction 정리

## 상태
COMPLETED

## 작업 목적
상태 변경/history/audit 원자성 확보

## 변경 파일
- ...

## 주요 변경
- ...

## QA
- Typecheck: PASS
- Unit: PASS
- Integration: PASS
- AI Review: PASS

## 위험도
HIGH

## 배포 주의
- DB schema 변경 없음
- 기존 API contract 유지

## 관련 Commit
- abc123

## 다음 작업
- 상태 변경 E2E 보강

이 Task Report는 일일 작업 보고서의 좋은 원본 데이터가 됩니다.

✅ 24. Task Status 설계

BACKLOG
READY
IN_PROGRESS
AI_WORKING
QA
REVIEW
BLOCKED
DONE
DEPLOYED

➕ 24-1. 흐름

READY
  ↓
IN_PROGRESS
  ↓
AI_WORKING
  ↓
QA
  ↓
REVIEW
  ↓
DONE
  ↓
DEPLOYED

➕ 24-2. 실패

QA
  ↓
BLOCKED
  ↓
IN_PROGRESS

작업 상태가 있으면 현재 어디까지 진행됐는지 자동화 도구가 판단하기 쉽습니다.

✅ 25. Task Metadata

taskId: 142
project: togethermall
type: refactor
domain: consult
risk: HIGH
status: READY
allowedPaths:
  - src/modules/consult
  - src/modules/audit-log
blockedPaths:
  - prisma
  - deployment
requires:
  - typecheck
  - consult-unit
  - consult-integration
requiresHumanReview: true

➕ 25-1. 활용

Prompt 생성
QA 선택
Scope 검사
Risk 판단
Report 생성

Metadata를 구조화하면 자동화의 정확도가 올라갑니다.

✅ 26. Risk 기반 Human Review

모든 작업을 같은 수준으로 검토할 필요는 없습니다.

➕ 26-1. LOW

문서
스타일
작은 UI

검토:
간단 diff 확인

➕ 26-2. MEDIUM

일반 CRUD
프론트 로직
조회 API

검토:
diff + test 결과

➕ 26-3. HIGH

상담 상태
Worker
외부 API
Export
Audit Log

검토:
상세 diff + integration test + QA report

➕ 26-4. CRITICAL

Auth
Permission
DB Migration
보안 설정
개인정보
운영 데이터 수정

검토:
반드시 수동 승인
배포 전 별도 점검

자동화 수준도 위험도에 따라 달라져야 합니다.

✅ 27. 한 번에 여러 AI Agent를 써야 할까?

초기에는 굳이 여러 Agent를 만들 필요는 없습니다.
역할을 논리적으로만 분리해도 충분합니다.

Worker Agent:
코드 작성

Reviewer:
diff 검토

QA:
deterministic test

Reporter:
작업 보고서 작성

➕ 27-1. 실제 구현 초기안

Codex:
코드 작업

Shell/CI:
검증

로컬 LLM:
요약/보고

사람:
최종 승인

별도 Agent 프레임워크를 먼저 도입할 이유는 없습니다.
역할 분리부터 시작하는 것이 좋습니다.

✅ 28. AI에게 다시 AI 결과를 검토시키는 구조

Codex A:
코드 수정

Reviewer Prompt:
diff만 검토

QA:
실제 명령 실행

➕ 28-1. 중요한 점

Reviewer가 Worker 설명을 그대로 믿지 않기
실제 Git diff 기준으로 검토
테스트 결과도 실제 실행 결과 사용

“AI가 자기가 잘했다고 말하는 것”은 검증이 아닙니다.
실제 diff와 테스트 결과가 기준이어야 합니다.

✅ 29. 작업 실패 기록

실패한 AI 작업도 기록할 가치가 있습니다.

# Failed Task Attempt

## Task
#142 상담 상태 변경 transaction

## 실패
Integration Test 실패

## 원인
AuditLogRepository가 transaction client가 아닌 기본 PrismaService 사용

## 자동 수정
1회 실행

## 결과
해결

## 재발 방지
Repository tx parameter 사용 규칙을 AI coding rule에 추가

자동화 실패도 규칙 개선 자료가 됩니다.

✅ 30. AI Coding Rules 자동 개선

반복적으로 AI가 같은 실수를 하면 프로젝트 규칙에 추가할 수 있습니다.

➕ 30-1. 반복 실수 예시

transaction 내부에서 Repository가 기본 Prisma 사용
Mapper 없이 Prisma 모델 반환
console.log에 response 출력
기존 API 필드 rename

➕ 30-2. 규칙으로 승격

Repository 메서드는 tx parameter를 지원해야 한다.
Use Case transaction 내부에서는 반드시 전달받은 tx를 사용한다.

➕ 30-3. 흐름

실패
  ↓
Troubleshooting
  ↓
재발 원인 분석
  ↓
AI Rule 추가
  ↓
다음 Codex 작업에 자동 포함

이렇게 되면 작업 기록이 실제 AI 개발 품질 개선으로 이어집니다.

✅ 31. 프로젝트 Knowledge 파일

docs/ai/
  architecture.md
  coding-rules.md
  common-mistakes.md
  security.md
  test-strategy.md

➕ 31-1. `common-mistakes.md`

# AI 작업 시 자주 발생한 문제

## Repository transaction 누락
- Use Case에서 transaction을 열어도 Repository가 기본 Prisma를 사용했던 사례가 있음.
- transaction 내부 호출에는 tx를 명시적으로 전달할 것.

## API 응답 변경
- 리팩토링 과정에서 기존 response field를 rename한 사례가 있음.
- API contract 변경은 별도 요구가 없으면 금지.

실제 실패 경험을 AI용 규칙으로 전환하면 점점 작업 정확도가 높아집니다.

✅ 32. 작업 자동화 CLI 전체 흐름

llm-work start 142
llm-work run 142
llm-work qa 142
llm-work review 142
llm-work finish 142

➕ 32-1. `start`

Issue/Task 읽기
Working Tree 확인
Branch 생성
Before Snapshot

➕ 32-2. `run`

Task Prompt 생성
Codex 작업
변경 파일 수집

➕ 32-3. `qa`

0908 QA pipeline 실행

➕ 32-4. `review`

Git diff AI Review
완료 조건 검토

➕ 32-5. `finish`

Commit message 후보
Task Report 생성
Daily Report 연결

한 번에 완전 자동화하지 않고 단계별 명령으로 시작하는 것이 안전합니다.

✅ 33. 단일 명령 자동화는 나중에

충분히 안정화되면:

llm-work execute 142

내부:

start
  ↓
run
  ↓
qa
  ↓
review
  ↓
사람 승인 요청

➕ 33-1. 자동으로 하지 않을 것

운영 배포
운영 migration
운영 데이터 수정
Critical 권한 변경 승인

개발 자동화와 운영 자동 실행은 분리해야 합니다.

✅ 34. 안전한 자동화 수준

Level 1:
보고서/요약 자동화

Level 2:
QA 자동화

Level 3:
Task Prompt/Branch 자동화

Level 4:
AI 코드 작업 + QA 자동 연결

Level 5:
제한적 자동 수정

Level 6:
자동 운영 배포

➕ 34-1. 현재 추천

현재:
Level 2~3

충분히 안정화 후:
Level 4

제한적으로:
Level 5

당분간 지양:
Level 6

자동화를 많이 하는 것이 성숙도가 아닙니다.
사람이 봐야 하는 지점을 정확히 남기는 것이 더 중요합니다.

✅ 35. 기존 자동화와 전체 연결

Issue / Task
  ↓
AI Coding
  ↓
QA Report
  ↓
Task Report
  ↓
Commit
  ↓
Deploy Note
  ↓
Daily Report
  ↓
Weekly Report
  ↓
Monthly Report
  ↓
Portfolio / Career Record

지금까지 만든 작업 기록 자동화가 하나의 흐름으로 연결됩니다.

✅ 36. 현재 프로젝트 적용 우선순위

➕ 36-1. 1순위: Task Spec 템플릿

목적
문제
범위
제외 범위
완료 조건
테스트
보안

완료 기준:

Codex 작업마다 같은 형식으로 요구사항 전달 가능

➕ 36-2. 2순위: Branch + Snapshot 자동화

Issue 번호 기반 branch
Working Tree 검사
base commit 기록

완료 기준:

AI 작업 전후 diff가 명확함

➕ 36-3. 3순위: Scope 검증

allowedPaths
blockedPaths
변경 파일 검증

완료 기준:

예상 범위 밖 변경 자동 경고

➕ 36-4. 4순위: QA + Task Report 연결

Codex 완료
  ↓
QA
  ↓
Review
  ↓
Task Report

완료 기준:

코드 수정부터 작업 기록까지 하나의 흐름으로 연결

처음부터 Agent 시스템을 만드는 것보다 이 네 단계를 먼저 구현하는 것이 훨씬 현실적입니다.

✅ 37. Codex에게 오케스트레이션 기능을 맡길 때 규칙

기존 local-llm-work-report 또는 별도 llm-work CLI에
AI 개발 작업 오케스트레이션 기능을 추가해줘.

목표:
Issue/Task → Branch → Codex 작업 준비 → QA → Review → Task Report 흐름을 관리하고 싶다.

조건:
1. llm-work start <task-id> 명령어를 만들어줘
2. Task Spec은 목적, 문제, 수정 범위, 제외 범위, 완료 조건, 테스트, 보안 항목을 가지게 해줘
3. 작업 시작 시 git working tree를 확인하고 변경사항이 있으면 기본적으로 경고해줘
4. 현재 branch, base commit, working tree 상태를 Before Snapshot으로 저장해줘
5. issue/task id 기준 branch 이름 후보를 생성해줘
6. allowedPaths와 blockedPaths를 지원해줘
7. AI 작업 후 git diff --name-only 기준으로 scope violation을 검사해줘
8. blockedPaths 변경은 BLOCK, allowedPaths 밖 변경은 WARNING으로 처리할 수 있게 해줘
9. Task Spec과 docs/ai의 프로젝트 규칙을 합쳐 Codex용 프롬프트를 생성해줘
10. Codex 작업 완료 후 변경 파일, 변경 요약, 테스트 결과, 미실행 테스트, 주의사항을 수집해줘
11. 기존 llm-report qa 파이프라인과 연결해 PASS/PASS_WITH_WARNINGS/BLOCK 결과를 사용해줘
12. type/lint 같은 명확한 실패만 제한적으로 자동 수정 재요청할 수 있게 해줘
13. 자동 재작업은 기본 최대 2회로 제한해줘
14. DB migration, permission, auth, security, production 관련 실패는 자동 수정하지 말고 사람 검토 대상으로 처리해줘
15. 완료 후 Task Report Markdown을 생성해줘
16. Task Report에는 task id, branch, base commit, 변경 파일, QA 결과, 위험도, commit 후보, 남은 TODO를 포함해줘
17. Secret, DATABASE_URL, Authorization header, 고객 개인정보는 AI prompt/report에 포함하지 않게 sanitize 해줘
18. 실제 commit/push/deploy는 기본 자동 실행하지 말고 사용자가 승인하도록 해줘
19. 실행 방법과 테스트 방법을 문서화해줘

➕ 37-1. 리뷰 기준

작업 범위를 명확하게 제한하는가?
AI 작업 전후 상태를 비교할 수 있는가?
QA를 실제 실행 결과 기준으로 판단하는가?
AI가 자기 결과를 스스로 성공으로 선언하지 않는가?
자동 재작업 횟수가 제한되는가?
DB/권한/보안 변경은 사람 검토로 남기는가?
commit/push/deploy를 무단 실행하지 않는가?
작업 결과가 기존 보고서 체계와 연결되는가?

✅ 38. 실무 체크리스트

➕ 38-1. Task 정의

작업 목적이 하나로 명확한가?
현재 문제가 적혀 있는가?
수정 범위가 정해져 있는가?
수정 제외 범위가 있는가?
완료 조건이 검증 가능한가?
테스트 조건이 있는가?
보안 조건이 있는가?
위험도가 정해져 있는가?

➕ 38-2. AI 작업 전

Working Tree가 깨끗한가?
올바른 branch인가?
base commit을 기록했는가?
Task Spec이 최신인가?
프로젝트 AI 규칙이 최신인가?
민감정보가 prompt에 없는가?
allowed/blocked path가 설정됐는가?
운영 DB/Secret 접근이 차단되어 있는가?

➕ 38-3. AI 작업 후

변경 파일 목록을 확인했는가?
작업 범위 밖 변경이 없는가?
typecheck가 통과했는가?
lint가 통과했는가?
필요한 테스트가 통과했는가?
API contract가 유지되는가?
개인정보/Secret 노출이 없는가?
Task 완료 조건을 충족하는가?

➕ 38-4. 완료

사람이 diff를 검토했는가?
QA Report가 생성됐는가?
Task Report가 생성됐는가?
commit message가 작업 목적을 설명하는가?
Issue와 commit이 연결되는가?
미완료 TODO가 남아 있는가?
Daily Report에 작업 결과가 반영되는가?
배포가 필요한 경우 Deploy Note가 준비됐는가?

✅ 39. AI에게 개발 작업 오케스트레이션을 물어볼 때 좋은 질문법

1인 개발 환경에서 AI/Codex를 활용한 개발 작업 오케스트레이션 시스템을 설계하려고 해.

환경:
1. NestJS + React + Prisma + PostgreSQL 기반 온라인 휴대폰 판매몰을 운영하고 있음
2. Codex로 기능 개발/리팩토링을 자주 진행함
3. 기존에 Git 기반 일일/주간/월간 보고서, Troubleshooting, QA Report 자동화 구조가 있음
4. 작업 하나를 Issue/Task 단위로 정의하고 싶음
5. Task에는 목적, 문제, 수정 범위, 제외 범위, 완료 조건, 테스트, 보안 조건을 넣고 싶음
6. 작업 시작 시 Working Tree와 base commit을 기록하고 issue 기반 branch를 만들고 싶음
7. Codex 작업 이후 allowedPaths/blockedPaths 기준으로 변경 범위를 검증하고 싶음
8. 기존 자동 QA를 실행해 typecheck, lint, test, secret scan, AI Review를 수행하고 싶음
9. 명확한 type/lint 오류 정도만 제한적으로 Codex에게 자동 수정시키고 싶음
10. DB migration, 권한, 보안, 운영 데이터 관련 변경은 반드시 사람이 승인해야 함
11. 최종 commit/push/deploy는 자동으로 실행하지 않고 사람 승인 단계가 필요함
12. 완료된 작업은 Task Report → Daily Report → Weekly/Monthly Report → Portfolio 후보로 연결하고 싶음

요청:
- Task Spec schema
- Issue/branch naming 규칙
- Working Tree/Before Snapshot 구조
- allowedPaths/blockedPaths scope 검증
- Codex prompt builder
- QA pipeline 연결 방식
- 실패 유형 분류
- 제한적 자동 재작업 방식
- Human Approval Gate
- Task Report 템플릿
- Task status/risk 모델
- AI coding rule 누적 방식
- CLI 명령어 설계
- 보안/운영 금지 기준
- 구현 우선순위
를 실무 기준으로 정리해줘.

➕ 39-1. AI 답변 검증 기준

코드 생성보다 Task 정의를 중요하게 보는가?
작업 범위를 작게 나누도록 권장하는가?
작업 전후 Git 상태를 비교하는가?
실제 테스트와 AI 리뷰를 구분하는가?
AI 결과를 AI 설명만으로 신뢰하지 않는가?
Scope violation을 감지하는가?
자동 수정 반복에 제한이 있는가?
DB/권한/보안 변경에 Human Gate를 두는가?
완전 자동 배포를 성급하게 권하지 않는가?
기존 보고/QA 자동화와 하나의 흐름으로 연결하는가?

📌 요약

개발 작업 오케스트레이션은 AI에게 코드를 작성시키는 것보다, 작업 정의부터 검증과 기록까지 하나의 흐름으로 관리하는 개념입니다.
AI/Codex 작업은 가능한 한 하나의 목표를 가진 작은 단위로 나눠야 변경 범위, 테스트, rollback, commit 관리가 쉬워집니다.
Task Spec에는 목적, 현재 문제, 수정 범위, 제외 범위, 완료 조건, 테스트 조건, 보안 조건을 포함하는 것이 좋습니다.
GitHub Issue나 로컬 Task를 기준점으로 두고 Branch, Commit, QA Report, Task Report를 연결하면 과거 변경 이유를 추적하기 쉬워집니다.
AI 작업 전에 Working Tree와 base commit을 기록해두면 작업 후 Git diff를 기준으로 예상 범위 밖 변경을 찾을 수 있습니다.
allowedPaths와 blockedPaths를 사용하면 Codex가 작업 목적과 관계없는 파일이나 DB/배포 설정을 수정하는 것을 감지할 수 있습니다.
프로젝트 공통 규칙은 docs/ai 같은 문서로 관리해 Controller, Use Case, Repository, transaction, 보안, 테스트 기준을 Codex 작업마다 재사용하는 것이 좋습니다.
AI 작업 결과는 AI가 작성한 설명이 아니라 실제 Git diff, typecheck, lint, 테스트 결과를 기준으로 검증해야 합니다.
0908의 QA 파이프라인을 연결해 PASS, PASS_WITH_WARNINGS, BLOCK 상태를 사용하면 작업 완료 여부를 구조적으로 관리할 수 있습니다.
자동 수정은 typecheck나 lint처럼 원인이 명확한 문제에만 제한적으로 사용하고, DB migration, Permission, Auth, 보안, 운영 데이터 변경은 반드시 사람이 검토해야 합니다.
자동 재작업은 2~3회 정도로 제한해 AI가 코드를 계속 흔드는 상황을 막아야 합니다.
사람 승인 단계의 목적은 모든 코드를 다시 처음부터 보는 것이 아니라, 자동화가 정리해준 변경 범위·위험도·테스트 결과를 바탕으로 최종 판단하는 것입니다.
작업 완료 후 Task Report를 만들고 이를 일일 → 주간 → 월간 → 포트폴리오 기록으로 연결하면 AI 개발 자체가 실무 성과 관리 체계와 이어집니다.
현재 단계에서는 복잡한 멀티에이전트 프레임워크보다 Task Spec → Branch/Snapshot → Codex 작업 → Scope 검증 → QA → Human Review → Task Report 흐름부터 만드는 것이 가장 현실적입니다.

juni

이전 포스트

TIL - 20260908

다음 포스트

TIL - 20260909

TIL

0909 운영 자동화/AI 워크플로우 심화 (5/N): 개발 작업 오케스트레이션과 AI 작업 단위 관리

✅ 1. 개발 작업 오케스트레이션이란 무엇인가?

➕ 1-1. 단순 AI 코딩과의 차이

✅ 2. 왜 작업 단위 관리가 중요한가?

➕ 2-1. 나쁜 작업 단위

➕ 2-2. 좋은 작업 단위

✅ 3. 작업 단위의 기본 구조

➕ 3-1. Task Spec 예시

✅ 4. Issue를 작업의 기준점으로 사용하기

➕ 4-1. Issue에 넣을 항목

➕ 4-2. 예시

✅ 5. Issue 크기 기준

➕ 5-1. 너무 작은 Issue

➕ 5-2. 적절한 Issue

➕ 5-3. 너무 큰 Issue

➕ 5-4. 판단 기준

✅ 6. Branch 자동 생성

➕ 6-1. 패턴

➕ 6-2. type 후보

➕ 6-3. CLI 예시

✅ 7. 작업 시작 전 Working Tree 확인

➕ 7-1. 깨끗한 경우

➕ 7-2. 변경사항이 있는 경우

➕ 7-3. 자동화 기준

✅ 8. Before Snapshot

➕ 8-1. 예시

➕ 8-2. 활용

✅ 9. AI 작업 프롬프트 자동 생성

➕ 9-1. 자동 포함할 내용

➕ 9-2. 기본 아키텍처 규칙

✅ 10. 프로젝트 규칙 파일

➕ 10-1. backend-rules.md

➕ 10-2. security-rules.md

➕ 10-3. 장점

✅ 11. 작업 범위 제한

➕ 11-1. Allowlist

➕ 11-2. Denylist

➕ 11-3. 작업 후 확인

➕ 11-4. 결과

✅ 12. 변경 범위 정책

➕ 12-1. 추천

✅ 13. Codex 작업 완료 후 받아야 할 결과

➕ 13-1. 예시

✅ 14. 완료 조건 자동 검증

➕ 14-1. 자동 확인 가능한 것

➕ 14-2. 사람이 확인해야 하는 것

✅ 15. 0908 QA 파이프라인 연결

➕ 15-1. 성공

➕ 15-2. 경고

➕ 15-3. 실패

✅ 16. 실패 유형 분류

➕ 16-1. 자동 수정 가능한 실패

➕ 16-2. 사람 검토가 필요한 실패

✅ 17. 제한적 자동 재작업

➕ 17-1. 재작업 프롬프트

➕ 17-2. 최대 횟수

✅ 18. Requirement Mismatch

➕ 18-1. 예시

➕ 18-2. 대응

✅ 19. 사람 승인 Gate

➕ 19-1. 승인 시 확인

✅ 20. Commit 자동 생성

➕ 20-1. 입력

➕ 20-2. 출력

➕ 20-3. 본문 예시

✅ 21. Commit과 Issue 연결

➕ 21-1. 장점

✅ 22. Push 전 최종 검사

➕ 22-1. 왜 staged diff만으로 부족한가?

➕ 22-2. Push 전 확인

✅ 23. 작업 완료 Report

✅ 24. Task Status 설계

➕ 24-1. 흐름

➕ 24-2. 실패

✅ 25. Task Metadata

➕ 25-1. 활용

✅ 26. Risk 기반 Human Review

➕ 26-1. LOW

➕ 10-1. `backend-rules.md`

➕ 10-2. `security-rules.md`

➕ 31-1. `common-mistakes.md`

➕ 32-1. `start`

➕ 32-2. `run`

➕ 32-3. `qa`

➕ 32-4. `review`

➕ 32-5. `finish`