사용자가 Claude Code로 직접 기획하고, Notion에서 Approved로 승인하면 Codex가 구현 → Claude(Sonnet)가 리뷰 → 커밋 → PR까지 자동 수행하는 AI 개발 파이프라인.
- 기획·개발 완전 분리: 기획은 사용자가 Claude Code로 직접, 구현은 Codex가 Approved task만 수행
- Approved 게이트:
devagent build는 Notion Status가 정확히Approved일 때만 진입 - 자율 사이클 루프: 리뷰 결과에 따라 자동 재구현 (CHANGES_REQUESTED → 다음 사이클)
- Sonnet 리뷰: 코드 리뷰는
claude-sonnet-4-5-20250929모델 고정 기본값 (config로 변경 가능) - Notion 본문 = 구현 명세: task 본문 markdown을 그대로 Codex에 inline spec으로 전달
- Git 통합: 사이클별 커밋, 자동 PR 생성, 원격 미설정 시 graceful skip
- Graceful degradation: Notion 동기화 실패가 본 작업을 막지 않음
┌──────────────────────────────────────────────────────────────┐
│ WorkflowService (Facade) │
│ executeBuildFromNotion / execute / resume / status │
└─────────────────┬────────────────────────┬───────────────────┘
│ │
┌─────────▼──────────┐ ┌─────────▼──────────────┐
│ Orchestrator │ │ Integrations (Notion) │
│ PipelineService │ │ - NotionClient │
│ │ │ - NotionStatusSync │
│ ┌──────────────┐ │ │ - NotionArtifactSync │
│ │Implementation│──┼───┼─► toggle blocks + │
│ │ (Codex) │ │ │ summary comments │
│ ├──────────────┤ │ └────────────────────────┘
│ │ Review │ │
│ │(Claude Sonnet)│ │
│ └──────────────┘ │
└────────────────────┘
기획은 claude 안에서 대화형으로 진행합니다. ./setup.sh가 devagent-planner 스킬을
~/.claude/skills/에 자동 설치하므로 아무 디렉토리에서나 사용할 수 있습니다.
claude
# > "Notion task <pageId> 기획해줘" ← 스킬이 자동 매칭되어 실행됨스킬이 수행하는 절차:
- Notion task 로드 (제목 + 본문 + Project Path 속성)
- 사용자와 대화하며 요구사항·구현 명세·테스트 시나리오 작성
- 완성된 구현 명세를 Notion 본문에 push (build는 Notion 본문을 spec으로 사용하므로 필수)
사용자는 Notion에서 기획 내용을 검토하고 직접 Approved로 승격:
devagent notion status <pageId> Approved- Notion Status가
Approved인지 검증 (아니면 즉시 거부) - task 본문 markdown을 inline spec으로 로드 (별도 Planning 없음)
- Implementation — Codex가 코드 작성 및 사이클 커밋
- Review — Claude(Sonnet)가 코드 리뷰 (APPROVED 시 종료, CHANGES_REQUESTED 시 재구현)
- Finalize — origin 있으면 push + PR, 없으면 로컬 보존
Notion Status 자동 전이 (build 단계만):
Approved → In Progress → In Review → Done (실패/중단 시 Approved로 복귀)
기존
devagent task <id>(기획부터 PR까지 무중단 자동) 명령은 제거되었습니다. 기획(plan)과 구현(build) 사이에는 반드시 사용자의Approved승인이 필요합니다.
여러 도메인을 병렬 기획해 Notion 페이지를 만들고, 한 번에 빌드하고 싶을 때 사용합니다.
build를 task마다 수동 실행하는 대신, DB의 모든 Approved task를 한 번에 처리합니다.
# 먼저 실행 스케줄(레인/순서)만 확인 — 실제 빌드 없음
devagent batch-build --dry-run
# 실제 일괄 빌드 (도메인 간 병렬, 같은 도메인 순차)
devagent batch-build --project /path/to/repo --concurrency 3스케줄링 규칙:
- task 제목 prefix로 도메인 식별 —
interview-1,interview-2,learning-1→interview/learning두 레인 - 같은 도메인(레인)은 슬라이스 번호 오름차순 순차 실행 — 같은 모듈/스키마/파일을 건드리고 슬라이스 간 의존이 있으므로 충돌 방지를 위해 직렬화
- 서로 다른 도메인 레인은 동시(병렬) 실행 — 기본 동시성 5,
--concurrency로 조절 - git worktree 격리 — 각 task는
origin/<baseBranch>에서 분리된 임시 worktree ($TMPDIR/devagent-worktrees/<domain>-<slice>-...)에서 빌드되어 단일 저장소에서도 병렬 빌드가 서로 간섭하지 않음. 완료 후 worktree는 자동 제거(--keep-worktrees로 보존) - 레인 내 실패 전파 — 한 슬라이스가 실패하면 같은 도메인의 후속 슬라이스는
skipped(의존 깨짐 방지). 다른 도메인 레인에는 영향 없음
Notion Status는 task별로 In Progress → Done(성공) 또는 Approved로 복귀(실패)
전이되며, 성공 시 PR 링크가 해당 페이지 코멘트로 기록됩니다.
| 옵션 | 설명 |
|---|---|
-p, --project <path> |
base 저장소 경로 (생략 시 Notion Project Path 속성) |
--db <id> |
Notion Database ID (생략 시 기본 DB) |
-c, --concurrency <n> |
도메인 레인 동시 실행 수 (기본 5, 최대 5) |
-m, --max-iterations <n> |
task당 최대 리뷰 반복 횟수 |
--dry-run |
실제 빌드 없이 실행 스케줄만 출력 |
--keep-worktrees |
빌드 후 임시 worktree 보존 (디버깅용) |
기획은 메인 PC에서 하고, 빌드는 별도 PC/서버에서 무인으로 돌리는 구성을 권장합니다. 빌드 PC는 Notion DB만 폴링하면 되므로 메인 PC와 직접 통신할 필요가 없습니다.
준비 (빌드 PC 1회):
git, Node.js 18+, Claude Code CLI, Codex CLI 설치 + 각 CLI 로그인- dev-agent 설치/빌드 (
./setup.sh) - Notion 인증을 메인 PC와 동일하게 등록
devagent notion login --token ntn_xxx --default-db <DB_ID>
- 대상 저장소를 clone하고
origin푸시 권한 확보(gh auth 등)
무인 루프 예시 (cron / 서비스로 등록):
#!/usr/bin/env bash
# 5분마다 Approved task를 모아 빌드. 빌드 PC의 crontab:
# */5 * * * * /path/to/batch-runner.sh >> ~/devagent-batch.log 2>&1
set -euo pipefail
cd /path/to/dev_agent
git -C /path/to/repo fetch origin # 최신 base 확보
exec devagent batch-build \
--project /path/to/repo \
--concurrency 3동작 원리상 안전한 이유:
batch-build는 매 실행마다 현재Approved인 task만 가져와 처리하므로, 이미Done이 된 task는 다시 빌드하지 않습니다(중복 방지).- 각 빌드는 격리된 worktree에서 이뤄지고 base 저장소의 작업 트리를 건드리지 않습니다.
- 동시 실행 중복을 막으려면
flock으로 단일 인스턴스를 보장하세요:flock -n /tmp/devagent-batch.lock devagent batch-build --project /path/to/repo || exit 0
📘 새 PC에서 처음 설치하는 경우 → SETUP.md 단계별 가이드 참조
- Node.js 18+
- git
- Claude Code CLI
- Codex CLI
git clone https://github.com/spring-kang/dev-agent.git
cd dev-agent
./setup.sh # macOS/Linux/WSL — 의존성 설치 + TypeScript 빌드 + 웹 빌드Windows(네이티브 PowerShell):
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\setup.ps1 # setup.sh와 동일한 7단계 수행Windows 상세 절차(WSL 포함)는 SETUP.md 참조.
git clone https://github.com/spring-kang/dev-agent.git
cd dev-agent
npm install
npx tsc # → dist/ 생성
./setup.sh실행 후에는devagent명령어가 전역으로 등록됩니다. (또는node dist/index.js로 대체 가능)
devagent notion login --token ntn_xxxxxxxxxxxx --default-db <NOTION_DB_ID># Stage 1: 기획 — claude 에서 devagent-planner 스킬 사용
claude
# > "Notion task 376e8963-3f9d-80bb-ac3e-d8818389de61 기획해줘"
# → 대화하며 기획 완성 + Notion 본문 push 후 종료
# → Notion에서 기획 검토 후 Status 를 "Approved" 로 변경
devagent notion status 376e8963-3f9d-80bb-ac3e-d8818389de61 Approved
# Stage 2: 구현 + 리뷰 + PR (Status=Approved 검증 후 실행)
devagent build 376e8963-3f9d-80bb-ac3e-d8818389de61 --project /path/to/project옵션 명시:
devagent build <pageId> --project /path/to/project --max-iterations 5직접 작업 지시 (Notion 없이):
devagent run \
--project /path/to/project \
"README에 사용법 섹션 추가하고 'docs: 사용법 추가' 메시지로 커밋"| 명령어 | 설명 |
|---|---|
build <pageId> |
승인된 Notion task 개발 실행 (Status=Approved 검증 필요) |
batch-build |
Notion DB의 모든 Approved task 일괄 빌드 (도메인 간 병렬 / 같은 도메인 순차, git worktree 격리) |
run <task> |
일반 워크플로우 실행 (Notion 비연동, 작업 설명 직접 입력) |
resume <project> |
중단된 워크플로우 복구 |
status [project] |
진행 상태 조회 |
list |
등록된 프로젝트 목록 |
serve |
웹 대시보드 서버 실행 |
devagent task <id>(기획~PR 무중단 자동)는 제거되었습니다. 기획(claude +devagent-planner스킬) → 사용자 검토/Approved승인 →build순서로 진행하세요.
| 명령어 | 설명 |
|---|---|
devagent notion login --token <T> [--default-db <ID>] |
토큰 저장 |
devagent notion logout |
토큰 제거 |
devagent notion test |
인증 확인 |
devagent notion list |
DB의 task 목록 |
devagent notion status |
통합 상태 조회 |
devagent notion status <pageId> <Status> |
페이지 Status 직접 변경 (예: Approved) |
devagent notion pull <pageId> [-o <file>] |
task 본문 markdown 추출 |
devagent notion push <pageId> --from <file> [--replace] |
markdown 파일을 본문에 append (--replace 시 기존 본문 교체) |
devagent notion comments <pageId> [-o <file>] |
페이지의 (열린) 댓글 조회 — 기획 수정 반영용 |
devagent rc |
로드된 .devagentrc 출력 |
기획 수정(댓글 반영): Notion 페이지에 댓글로 피드백을 남긴 뒤 claude 에서 "이 티켓 댓글 반영해줘" 라고 하면 devagent-planner 스킬이 댓글을 읽어 (
notion comments) 명세에 반영하고 본문을 교체(notion push --replace)한다. 댓글 resolve 와 Status 재전환(Approved)은 Notion UI 에서 직접 한다.
| 옵션 | 설명 | 기본값 |
|---|---|---|
-p, --project <path> |
프로젝트 경로 | rc 설정 또는 Notion Project Path 속성 |
-m, --max-iterations <N> |
최대 사이클 수 | 5 |
| 옵션/인자 | 설명 | 기본값 |
|---|---|---|
<task> (인자) |
작업 설명 텍스트 | 필수 |
-p, --project <path> |
작업 대상 경로 | 필수 |
-m, --max-iterations <N> |
최대 사이클 수 | 5 |
--verbose |
상세 로그 | false |
자주 쓰는 옵션을 프로젝트 루트(또는 상위 디렉토리)나 ~/.dev-agent/devagentrc.json에 저장해두면 매번 옵션을 지정하지 않아도 됩니다.
우선순위 (높은 → 낮은):
- CLI 옵션 (
--task 등) - 환경변수
DEVAGENT_* - 프로젝트
.devagentrc.json(cwd 기준 walk-up) - 글로벌
~/.dev-agent/devagentrc.json
지원 키:
{
"task": "376e8963-3f9d-80bb-ac3e-d8818389de61",
"projectPath": "/Users/me/projects/foo",
"maxIterations": 10,
"verbose": true,
"notion": { "defaultDatabaseId": "<DB_ID>" }
}환경변수 매핑:
DEVAGENT_TASKDEVAGENT_PROJECT_PATHDEVAGENT_MAX_ITERATIONSDEVAGENT_VERBOSE(1/true)DEVAGENT_DEFAULT_DB
확인:
devagent rc # 어떤 소스에서 어떤 값이 적용됐는지 표시| 속성명 | 타입 | 용도 |
|---|---|---|
Name |
Title | 작업 제목 |
Status |
Status / Select | 워크플로우 상태 자동 전이용 |
Project Path |
Rich text | 작업 대상 로컬 경로 |
To Do(또는Not started) — 기획 전/기획 중인 taskApproved— 사용자가 기획 검토 후 직접 설정.devagent build진입 조건.In Progress— build 시작 시 자동 전이In Review— build 의 코드 리뷰 단계에서 자동 전이Done— 완료 시 자동 전이
라벨이 다르면
integrations.json의statusMapping으로 매핑 가능.build명령은 Status 가 정확히Approved인 경우에만 진행하며, 그 외에는 즉시 거부합니다. 실패/중단 시 Status 는Approved로 복귀하므로 수정 후 재시도할 수 있습니다.
Settings → Integrations → Capabilities에서 활성화:
- ✅ Read content
- ✅ Update content
- ✅ Insert content
- ✅ Insert comments
# 작업 제목
## 목표
한 문장으로 무엇을 달성할지
## 컨텍스트
배경 정보, 왜 필요한지
## 요구사항
- 대상 파일/경로
- 변경 내용
- 커밋 메시지: `docs: 한국어 컨벤션 메시지`
## 수용 기준
- [ ] 자동 검증 가능한 조건 1
- [ ] git log -1 --pretty=%s 결과 일치좋은 티켓의 조건:
- 목표가 한 문장으로 요약 가능
- 수용 기준이 자동 검증 가능
- 커밋 메시지는 backtick으로 감싸기 (자동 추출 패턴)
- Project Path 속성 필수
<project>/
├── .ai-workflow/
│ ├── current/
│ │ ├── artifacts/ # 기획 산출물 (run 모드에서만 생성)
│ │ │ ├── requirements.md
│ │ │ ├── implementation-spec.md
│ │ │ └── test-scenarios.md
│ │ └── state.json
│ └── archive/
└── (소스 코드 변경 + git 커밋)
build모드에서는 Notion 본문 자체가 구현 명세(inline spec)로 사용되므로 artifacts/ 파일 생성 없이 바로 Implementation 으로 진입합니다.
- 새 브랜치:
ai/YYYYMMDD-HHMMSS-<task-slug> - 사이클별 커밋 (spec에서 메시지 자동 추출)
- origin 있으면 push + PR, 없으면 로컬 브랜치 보존
- Status 자동 전이
- 본문에 사이클별 toggle 블록 추가
- 코멘트로 사이클별 진행 요약
src/
├── cli/ # CLI 진입점
├── components/ # 핵심 컴포넌트
│ ├── claude-agent.ts # Claude Code 래퍼
│ ├── codex-agent.ts # Codex 래퍼
│ ├── git-manager.ts # git 작업
│ ├── state-manager.ts # 워크플로우 상태 관리
│ └── ...
├── services/ # 비즈니스 로직
│ ├── workflow.service.ts # Facade
│ ├── pipeline.service.ts # 사이클 루프
│ └── ...
├── integrations/ # 외부 통합
│ ├── notion-client.ts
│ ├── notion-status-sync.ts
│ ├── notion-artifact-sync.ts
│ └── notion-block-appender.ts
├── orchestrator/ # 워크플로우 오케스트레이션
├── types/ # 타입 정의
├── web/ # 웹 서버 (Express + Socket.IO)
└── container.ts # DI Composition Root
npm run dev # tsx로 즉시 실행
npm test # 단위 테스트
npm run typecheck # 타입 체크
npm run lint # ESLint
npm run format # Prettier
npm run web:dev # 웹 대시보드 dev 서버| 증상 | 해결 |
|---|---|
Insufficient permissions for /comments |
Notion Integration에서 Insert comments 활성화 |
프로젝트 경로가 지정되지 않았습니다 |
Project Path 속성 추가 또는 --project-path 사용 |
커밋 메시지가 [ai-cycle-N] Auto-generated |
spec에 커밋 메시지: \...`` 형식으로 백틱 사용 |
원격 저장소(origin)가 설정되어 있지 않아 |
정상 — 로컬 브랜치에 보존됨 |
| Notion task 로드 실패 | DB/페이지 Connections에 Integration 추가 |
MIT