DeukAgentFlow Architecture

Deuk Agent Flow v5.0.2

deuk-flow npm version deuk-agent-flow npm downloads

AI 코딩 작업이 대화창 밖으로 흘러내리지 않게.

"다음", "진행", "정리"처럼 짧게 말해도 티켓, 범위, 검증, 기억이 레포에 붙어 있게 만듭니다.

Deuk Family 생태계의 핵심 모듈입니다.

English · 한국어

--- **Deuk Agent Flow**는 AI가 참여하는 작업 공간을 위한 레포 소유 워크플로우 계층입니다. 기획, 소프트웨어 엔지니어링, 시스템 운영, 리서치 같은 다양한 환경을 Codex, Copilot, Cursor, Claude Code, Gemini, Windsurf, 그리고 다음에 쓰게 될 에이전트까지 같은 티켓 흐름으로 묶습니다. 대부분의 에이전트 설정은 "지침"에서 멈춥니다. Deuk Agent Flow는 짧은 대화를 작업 루프로 바꿉니다: 티켓, 범위, 실행, 검증, 보관. 긴 명령을 외우지 않아도 `AGENTS.md`, Copilot instructions, Cursor rules, Claude skills 같은 표면을 같은 흐름으로 묶습니다. 후킹 포인트는 단순합니다. 사용자가 "다음", "원인", "정리"라고만 해도 현재 에이전트가 그 의미를 붙잡을 레포 소유의 장소가 생깁니다. 진행 중인 작업은 `~/.deuk/tickets/`에, 결정과 계획과 완료 근거는 코드베이스 옆에 남습니다. **Deuk Agent Flow**는 워크플로우 계층입니다. 이 흐름 전체에 별도 companion 제품인 **Deuk AgentContext**를 꽂으면 레포 전체가 확장된 프로젝트 브레인을 얻습니다. 검색 가능한 기억, 재사용되는 결정, 다음 에이전트가 실제로 쓰는 팀 패턴까지 붙습니다. ### 왜 지금인가 AI 코딩은 이미 장난감 단계를 넘어 production volume으로 들어갔습니다. - Google은 **새 코드의 75%가 AI 생성**이라고 밝혔습니다. 2024년 25%, 작년 가을 50%에서 빠르게 올라간 흐름입니다. ([Semafor, 2026](https://www.semafor.com/article/04/24/2026/google-ceo-says-75-of-companys-new-code-is-ai-generated)) - Sonar의 2026 개발자 설문 보도에 따르면 현재 AI 생성 코드는 약 **42%**, 2027년에는 약 **65%**까지 오를 것으로 예상됩니다. ([TechRadar, 2026](https://www.techradar.com/pro/devs-dont-trust-ai-code-but-many-say-they-still-dont-check-it-anyways)) - Stack Overflow 2025 설문 보도에서는 개발자 **84%**가 AI 도구를 쓰거나 쓸 계획이지만, "거의 맞지만 틀린 답"과 AI 코드 디버깅이 핵심 불만으로 꼽혔습니다. ([InfoWorld, 2025](https://www.infoworld.com/article/4031673/ai-use-among-software-developers-grows-but-trust-remains-an-issue-stack-overflow-survey.html)) - Faros는 AI 도입 뒤 작업량은 늘었지만, **개발자당 버그 54% 증가**, 리뷰 시간 5배 증가, PR 대비 incident 증가라는 불편한 결과를 보고했습니다. ([ADTmag, 2026](https://adtmag.com/articles/2026/04/22/more-code-more-bugs.aspx)) 이제 병목은 코드를 더 빨리 쓰는 능력이 아닙니다. 에이전트 작업을 범위 안에 붙잡고, 리뷰 가능하게 만들고, 검증하고, 다음 세션에서도 이어받게 만드는 능력입니다. ### 그래서 뭐가 달라지나 | 없을 때 | Deuk Agent Flow 사용 시 | |---|---| | "다음"이 대화 기억에 의존 | "다음"이 레포 티켓으로 이어짐 | | 에이전트가 요청 밖까지 수정 | APC 범위가 수정 가능 경계를 잡음 | | 리뷰어는 코드만 보고 의도를 추측 | 티켓에 원인, 계획, 근거가 같이 남음 | | AI 출력이 리뷰 부담을 키움 | 검증과 closeout이 작업 루프에 포함됨 | | 대화가 끝나면 맥락도 사라짐 | archive와 지식 증류로 프로젝트 기억이 남음 | ### 1분 시각화 ```text 짧은 대화 "다음" / "원인" / "정리" | v Deuk Agent Flow 티켓 + 범위 + 검증 + 기억 | v 레포에 남는 작업 리뷰 가능한 변경 + 결정 근거 + 다음 세션 연결 ``` | 장점 | 체감 | |---|---| | 맥락 손실 감소 | 다음 에이전트가 대화 전체를 다시 안 물어도 이어감 | | 범위 이탈 감소 | 티켓이 바꿔도 되는 것과 안 되는 것을 잡음 | | 리뷰 추측 감소 | diff 옆에 의도와 근거가 같이 남음 | | generated 코드 위험 감소 | 수정 전에 source/generator 소유자를 확인 | | 팀 기억 강화 | 완료된 작업이 검색 가능한 프로젝트 히스토리가 됨 | > **현재 배포 기준:** > v5.0.0은 내부 시스템 전면 개편 메이저 릴리스입니다. 전역 저장소가 `~/.deuk/tickets/{uuid}/` (홈 기반)으로 이전되어 멀티 워크스페이스 공존·세션 인계가 가능합니다(기존 `~/.deuk-agent/`는 자동 마이그레이션 — 위 [업그레이드 가이드](#-50-업그레이드--홈-디렉토리-마이그레이션) 참고). XState 기반 티켓 워크플로 엔진과 VS Code Flow UI(첫 배포)가 도입되었고, 스킬 시스템과 persona-maid·doc-sync 스킬이 홈 디렉토리로 통합되었습니다. **Claude Code** 환경에 최적화되어 있으며, Deuk AgentContext MCP는 선택형 기억 계층으로 `init`과 별도로 설정합니다. > **아키텍처 기반:** > 거대하고 무거운 레거시 `.cursorrules` 방식을 공식적으로 폐기했습니다. v3.0은 `AGENTS.md`를 단일 진실 공급원으로 사용하는 **Hub-Spoke 모델**을 도입하여, IDE별 규칙은 얇은 진입점 포인터 역할만 수행합니다. ### 🗺️ 핵심 기능 및 아키텍처 (Main Features) Deuk Agent Flow는 AI 에이전트가 코드를 분석하고 작성하는 흐름을 안정적으로 이끄는 **4대 핵심 기능**을 제공합니다. 1. **Zero-Copy Hub-Spoke 아키텍처** - **Hub**: 단일 진실 공급원인 `AGENTS.md` (글로벌 룰) - **Spoke**: `PROJECT_RULE.md` 등 워크스페이스별 로컬 규칙 - **효과**: IDE별(Cursor, Copilot, Windsurf) 설정 파일 중복을 제거하고, 에이전트가 오직 하나의 규약만 바라보게 하여 지시 사항의 충돌과 환각을 원천 차단합니다. 2. **티켓 주도 워크플로우 (TDW: Ticket-Driven Workflow)** - 계획(Plan) → 실행(Execute) → 검증(Verify) → 보관(Archive)의 분명한 라이프사이클로 작업을 이끕니다. - 활성화된 티켓(`ACTIVE_TICKET.md`)을 중심으로 변경을 연결해 범위와 진행 상태가 계속 보이게 합니다. - CLI가 소유하는 workflow state table로 phase transition을 계산하고, DocMeta 기반 compact action surface를 에이전트에게 제공합니다. 3. **플랫폼 공존 및 모드 인지형 게이트 (Mode-Aware Workflow Gate)** - 에이전트의 현재 모드(Plan Mode vs. Execute Mode)를 인지하여, Plan Mode에서는 분석과 구현 계획서(Artifacts) 작성에 집중하도록 APC를 적용합니다. - MCP(Model Context Protocol) Soft Gate와 연동되어 현재 티켓 컨텍스트에 맞는 변경 흐름을 유지합니다. 4. **지식 증류 및 Zero-Legacy (Knowledge Distillation)** - 완료된 작업은 `reports/`로 아카이빙되며, 이 과정에서 **Zero-Token 지식 증류** 기술이 적용되어 핵심 히스토리만 벡터 DB(DeukAgentContext)로 전달됩니다. - 불필요한 과거 로그나 사용되지 않는 `.cursorrules` 스텁을 자동으로 청소하여 컨텍스트 윈도우 낭비를 막습니다. ### 지침 파일만으로 부족한 이유 이미 AI 코딩 에이전트 생태계에는 `AGENTS.md`, GitHub Copilot instructions, Cursor rules, Claude skills, 여러 에이전트 실행 도구, 일반 LLM 가드레일이 있습니다. Deuk Agent Flow는 이들과 경쟁하기보다 그 위에 **티켓 기반 레포 흐름**을 얹습니다. | 비슷한 접근 | 도움이 되는 부분 | Deuk Agent Flow가 더하는 것 | |---|---|---| | `AGENTS.md` 공개 형식 | 코딩 에이전트가 읽을 공통 지침 파일 | 티켓 생명주기, Phase Gate, 검증, 아카이브 가능한 기억 | | Copilot instructions / Cursor rules / Claude memory | 도구별 맞춤 지침 | 여러 에이전트가 공유하는 레포 소유 워크플로우 | | Claude/Copilot custom agent와 skill | 재사용 가능한 작업 playbook | skill이 워크플로우를 대체하지 않고 티켓 실행으로 들어가게 함 | | 에이전트 실행기와 harness | 여러 코딩 에이전트 실행 | 어떤 에이전트를 쓰든 레포 안에서 생명주기를 통제 | | 일반 LLM/MCP 가드레일 | 런타임 정책 검사 | 작업 지시서, 범위 계약, 깃에 남는 기록, 완료 근거 | Deuk Agent Flow는 AI 코딩 작업을 팀이 이해하고 이어받기 쉬운 흐름으로 만들고 싶을 때 특히 잘 맞습니다. 여러 파일에 걸친 변경, 검증, 기록, 다음 작업 연결이 자연스럽게 이어지도록 돕는 데 초점을 둡니다. ### Karpathy식 skill과 같이 쓰면 좋은 점 Karpathy식 skill은 한 작업 안에서 에이전트의 행동을 더 좋게 만드는 데 강합니다. Deuk Agent Flow는 그 작업을 레포 차원에서 티켓화하고, 범위를 맞추고, 검증하고, 다시 찾을 수 있게 남기는 데 강합니다. 둘을 함께 쓰면 skill은 작업 수행 품질을 끌어올리고, Deuk Agent Flow는 그 결과를 팀 흐름에 연결합니다. 앞단에서는 행동 playbook이 작동하고, 뒷단에서는 티켓 생명주기와 DeukAgentContext 기억 계층이 남습니다. ### 로드맵 **v5.0에서 배포됨** — companion 표면이 도착했습니다: VS Code **Flow UI**(첫 배포)가 사이드바에서 active ticket·phase·open ticket count를 보여줍니다. 전역 저장소가 홈 디렉토리(`~/.deuk`)로 이전되어 워크스페이스 간 연속성이 확보됐고, 스킬 시스템(페르소나·doc-sync 포함)이 통합·홈 동기화됐습니다. **다음** — 티켓 DocMeta 갱신 경로 안정화, DeukAgentContext 기억 연동 심화(phase/memory status 표면 강화), 모든 CLI·티켓 표면이 완전 현지화되도록 i18n 커버리지 확대. 목표는 그대로입니다 — 팀이 쓰는 코딩 에이전트를 바꾸지 않고도 같은 작업 규율을 얻는 것. ### 📚 상세 문서 | 문서 | 용도 | |---|---| | [docs/usage-guide.ko.md](docs/usage-guide.ko.md) | **[추천]** 실전 배포 및 단계별 사용 가이드 | | [docs/skills-guide.ko.md](docs/skills-guide.ko.md) | **v5.0 신규:** 스킬 시스템·페르소나 사용법·Flow UI 가이드 | | [Flow UI 가이드](docs/skills-guide.ko.md#4-vs-code-flow-ui-agentflow-panel) | AgentFlow Panel — 워크스페이스·스킬 탭, 핸드오프, 활용 팁 | | [docs/architecture.ko.md](docs/architecture.ko.md) | 고수준 시스템 구조 및 시각적 인포그래픽 | | [docs/how-it-works.ko.md](docs/how-it-works.ko.md) | 상세 CLI 메커니즘, ticket workflow 런타임, 초기화 생명주기 및 파일 역할 | | [docs/principles.ko.md](docs/principles.ko.md) | 설계 철학: Hub-Spoke, Zero-Legacy, 소스 주권 | | **English Docs** | [README.md](README.md) · [docs/architecture.md](docs/architecture.md) | --- ## 🧩 VS Code 확장 — AgentFlow Panel > **v5.0 신규 (첫 배포)** — AgentFlow Panel을 설치하면 VS Code 사이드패널에서 티켓 워크플로우 전체를 제어할 수 있습니다. 터미널 전환 불필요. 티켓이 `~/.deuk/tickets/`에 저장되어 워크스페이스 간 연속성이 보장됩니다.

AgentFlow Panel — VS Code 보조 사이드바의 티켓 목록
AgentFlow Panel — Workspace 탭의 티켓 목록·상태 필터·활성 티켓 chip.

### 워크플로에 UI를 활용하면 좋은 점 CLI 티켓 명령만으로도 워크플로를 돌릴 수 있지만, Flow UI를 곁들이면 **컨텍스트 전환 비용**이 크게 줄어듭니다. | 상황 | CLI만 | Flow UI 활용 | |---|---|---| | 지금 어떤 티켓이 열려 있나? | `ticket status` 입력 | 사이드바에서 항상 노출 | | 다른 티켓으로 넘어가기 | id 외워서 `ticket use` | 목록 클릭 한 번 | | AI 챗에 컨텍스트 전달 | 수동 복사·붙여넣기 | **핸드오프** 버튼 → 클립보드 바로 복사 | | 스킬 ON/OFF 조절 | `skill expose/unexpose` | 토글 클릭, 플랫폼별 개별 제어 | | 티켓 상태·phase 변경 | `ticket move` 명령 | **상태 변경** 버튼 → 다이얼로그 | > 터미널을 닫지 않아도 되고, 명령어를 외울 필요도 없습니다. 에이전트가 작업 중일 때 **사이드바로 흐름을 모니터링**하면서 필요한 시점에만 개입할 수 있습니다. > > → 상세 사용법: [Flow UI 가이드](docs/skills-guide.ko.md#4-vs-code-flow-ui-agentflow-panel) --- | 기능 | 설명 | |---|---| | **티켓 목록** | 1행 고밀도 포맷: 파일명 · m/s · phase · priority · 본문 스니펷 · 날짜 | | **상태 필터** | Open / Close / All + 툴바에 활성 티켓 ID 강조 chip | | **검색 팝업** | id·title·summary·body 전문 실시간 검색 | | **미리보기 패널** | 파일명 + phase/priority + **open** 단쳐를 1줄로 표시 | | **Copy handoff** | textarea 옆 고정 버튼 — `id / title / phase·status·priority / summary / continue ticket`을 클립보드에 복사, AI 챗에 바로 붙여넣기 | | **멀티 워크스페이스** | 워크스페이스 셀렉터; 중첩 워크스페이스 탐지는 agent-rule 경계에서 자동 중단 | ### 설치 ```bash # 소스 빌드 cd /path/to/DeukAgentFlow npm run bundle:vscode npm run install:vscode ``` `npm run install:vscode`는 번들된 VSIX를 데스크톱 VS Code와 VS Code Server에 함께 설치하고, 오래된 `deukpack.deuk-agent-flow-*` 폴더를 정리한 뒤, AgentFlow 관련 workspace webview 상태를 백업 후 초기화해 여러 workspace에 남아 있던 오래된 패널 상태가 다시 살아나지 않도록 합니다. 또는 [releases 페이지](https://github.com/joygram/DeukAgentFlow/releases)에서 최신 `deuk-agent-flow.vsix`를 다운로드하고 **Extensions → Install from VSIX…** 로 설치하세요. --- ## 🚀 빠른 시작 (Quick Start) 가장 빠르게 Deuk Agent Flow를 현재 작업 프로젝트에 도입하는 방법입니다. ```bash # 1. 글로벌 설치 npm install -g deuk-agent-flow # 2. 프로젝트 초기화 (AGENTS.md 및 설정 생성) deuk-agent-flow init ``` 대화형 init의 선택지는 workspace 용도 질문 하나로 끝납니다. 문서 언어, workflow mode, ticket 공유, agent pointer, MCP memory 기본값은 프로젝트 디렉터리 성격으로 추론하거나 private 기본값으로 처리합니다. 이후 일상 작업은 명령을 직접 치기보다 에이전트에게 짧게 말합니다. 예: "진행", "다음", "원인 다시 파악". 단일 저장소라면 해당 저장소 루트에서 `deuk-agent-flow init`을 실행합니다. 여러 DeukAgentFlow 프로젝트를 포함한 루트 워크스페이스라면 그 워크스페이스 루트에서 같은 명령을 실행합니다. `init`은 루트 포인터와 자체 `PROJECT_RULE.md` / `.deuk-workspace-id` 마커를 가진 하위 워크스페이스를 함께 갱신합니다. 이렇게 사용하면 효과가 극대화됩니다. workspace 루트는 공통 진입점, 각 프로젝트 루트는 독립 티켓/규칙/검증 단위로 나누고, 중첩 서버나 앱은 필요할 때 별도 프로젝트로 초기화하세요. 자세한 실전 활용법은 **[실전 사용 가이드](docs/usage-guide.ko.md)**를 참조하세요. ## 🛠️ 설치 및 설정 ### 1. 글로벌 설치 (일반 사용자) `npx` 캐시 문제와 "로컬 트랩"을 방지하기 위해 글로벌 설치가 엄격히 권장됩니다. ```bash npm install -g deuk-agent-flow deuk-agent-flow init ``` 기존 저장소에 새 버전을 반영할 때는 먼저 글로벌 패키지를 업데이트한 뒤 init을 다시 실행합니다. ```bash npm install -g deuk-agent-flow deuk-agent-flow init ``` `init`은 현재 설치된 패키지의 규칙을 다시 적용하고 legacy/runtime template copy를 제거합니다. 글로벌 npm 패키지 업데이트 자체를 자동으로 수행하지는 않습니다. 단일 저장소라면 해당 저장소 루트에서 `deuk-agent-flow init`을 실행합니다. 여러 DeukAgentFlow 프로젝트를 포함한 루트 워크스페이스라면 그 워크스페이스 루트에서 같은 명령을 실행합니다. `init`은 루트 포인터와 자체 `PROJECT_RULE.md` / `.deuk-workspace-id` 마커를 가진 하위 워크스페이스를 함께 갱신하므로, 일반 사용자도 새 패키지 버전을 설치한 뒤 자신의 개인 워크스페이스 루트에서 AI agent rule을 갱신할 수 있습니다. 사용하는 AI client 선택은 한 번으로 고정되지 않습니다. 나중에 다른 client를 쓰게 되면 `deuk-agent-flow init`을 다시 실행하고 추가할 AI client를 선택하면 됩니다. ### 2. 로컬 소스 개발 (메인테이너/파워 유저) 글로벌 명령은 기본적으로 설치된 패키지를 실행합니다. 다른 프로젝트 디렉터리에서 로컬 checkout 소스를 실행해야 하는 개발자는 명시적으로 로컬 소스 라우팅을 켜야 합니다. ```bash cd ~/workspace/DeukAgentFlow sudo npm link DEUK_AGENT_FLOW_USE_LOCAL=1 deuk-agent-flow init # 로컬 scripts/cli.mjs로 라우팅됨 ``` Codex나 Copilot을 주로 사용한다면 이 구성이 일상 운영에 가장 적합합니다. 현재는 이 두 환경에서 Hub-Spoke와 티켓 기반 워크플로우가 가장 부드럽게 동작합니다. ### 3. 메인테이너 배포 메인테이너는 루트에서 한 번의 명령으로 배포할 수 있습니다. ```bash npm run publish ``` 이 흐름은 한 번의 실행으로 `deuk-flow` 릴리스 표면 아래 npm 패키지 두 개를 모두 등록해야 합니다. - `deuk-flow` canonical 패키지: `deuk-agent-flow` - `deuk-flow` 레거시 호환 alias 패키지: `deuk-agent-rule` 배포 스크립트는 먼저 alias 패키지의 version/dependency를 동기화하고, 그 다음 canonical 패키지를 publish한 뒤 alias 패키지를 publish합니다. npm registry에 쓰기 전에 dry-run으로 먼저 확인하세요. ```bash npm run publish:dry ``` 배포 전에는 Docker consumer smoke test를 실행합니다. 이 검증은 깨끗한 Node 컨테이너에 packed package를 설치하므로, 로컬 `npm link`나 global package가 의존성 누락을 숨기지 못합니다. ```bash npm run smoke:npm:docker ``` --- ## 🔄 5.0 업그레이드 — 홈 디렉토리 마이그레이션 **5.0은 전역 저장소를 `~/.deuk-agent/`에서 `~/.deuk/`로 옮깁니다.** 자동·멱등·자가치유 방식이라 `init`마다, 그리고 업그레이드 후 첫 티켓 명령에서 실행됩니다. 보통은 아무것도 안 하셔도 됩니다. **동작 방식 (`ensureWorkspaceMigrated`):** - **레거시만 있을 때** → `~/.deuk/`로 이름 변경(빠른 경로). 이름 변경이 실패하면(다른 에이전트가 디렉토리를 점유, `EBUSY`/`EPERM` 등) 재귀 복사로 폴백하고 **원본 `~/.deuk-agent/`는 그대로 보존**합니다. - **둘 다 있을 때**(복사 후 잔여물) → `~/.deuk/`에 실제 데이터가 있는 것을 확인한 **후에만** 레거시 디렉토리를 제거하고, 이후 실행마다 재시도합니다. - **안전장치** → `~/.deuk/`가 비어 있으면 레거시 디렉토리를 **절대** 삭제하지 않습니다(미완성 복사로 인한 데이터 유실 방지). **수동 복구 (자동 마이그레이션이 완료되지 않은 경우):** 1. **무엇이 있는지 확인** — 티켓이 최우선입니다: ```bash ls -la ~/.deuk/tickets ~/.deuk-agent/tickets 2>/dev/null ``` 2. **`~/.deuk/`가 비었거나 없고 `~/.deuk-agent/`에 데이터가 있을 때** → 원본을 백업으로 남긴 채 직접 복사: ```bash cp -r ~/.deuk-agent ~/.deuk ``` 3. **둘 다 있고 `~/.deuk/`에 최신 티켓이 있을 때** → 레거시는 오래된 잔여물입니다. `~/.deuk/`가 올바른지 확인한 뒤 제거: ```bash rm -rf ~/.deuk-agent ``` 4. **티켓 명령을 다시 실행**(예: `deuk-agent-flow rules ticket --workspace `) — 자가치유 패스가 남은 잔여물을 자동으로 정리합니다. > ⚠️ `~/.deuk/`가 비어 있는 동안 `~/.deuk-agent/`를 절대 삭제하지 마세요 — 과거 티켓의 유일한 사본입니다. 자동 안전장치도 이를 거부하니, 수동 작업 시에도 동일하게 지키세요. --- ## 🎯 프로토콜 워크플로우 워크플로우는 **티켓 기반 실행 계약(Ticket-Driven Execution Contract)**에 의해 통제됩니다. 1. **스캐폴딩 (Scaffolding)**: `init` 명령어가 `AGENTS.md`와 `PROJECT_RULE.md` 같은 로컬 포인터를 배치합니다. 런타임 템플릿은 워크스페이스별 복사본이 아니라 패키지의 `templates/`를 단일 진실 공급원으로 사용합니다. 2. **티켓팅 (Plan Phase)**: 사용자가 짧게 지시하면 에이전트가 맥락을 읽고 내부 작업 지시서를 생성합니다. 이때 에이전트는 Plan Mode로 동작하며 코드를 수정할 수 없고 계획 수립에만 집중합니다. 3. **실행 (Execute Phase)**: 사용자의 승인을 받은 후, 에이전트는 **타겟 서브모듈**에 고정되어 실질적인 코드 작성을 수행합니다. MCP Soft Gate가 인가되지 않은 파일의 수정을 감시합니다. 4. **검증 (Verify Phase)**: 개발 작업 종료 전 사이드 이펙트 감사(Audit) 및 컨벤션(DC-DUP 등 아키텍처 규칙) 체크를 수행합니다. 5. **아카이빙 (Archive Phase)**: 완료된 티켓은 Zero-Token 지식 증류를 거쳐 `reports/`로 이동하며, 이 데이터는 DeukAgentContext 벡터 데이터베이스에 저장되어 영구적인 **엔지니어링 메모리 엔진**으로 작동합니다. --- ## ⚙️ 에이전트에게 말로 요청하기 일상 사용자는 티켓 명령을 외울 필요가 없습니다. 짧게 말하면 에이전트가 맥락, CLI, 티켓 파일을 처리합니다. | 하고 싶은 일 | 이렇게 말해도 됨 | |--------|------| | 새 작업 시작 | *"티켓 잡고 진행"* | | 기존 작업 이어가기 | *"다음 진행"* | | 코딩 전 검토 | *"원인 먼저 파악"* | | 완료 처리 | *"검증 기록하고 정리"* | | skill 관리 | *"safe-refactor 추가"* | ### 티켓 파일 깃 관리 원칙 - `~/.deuk/tickets/**/*.md`와 `INDEX*.json`은 CLI가 바꾼 결과만 반영합니다. - 티켓 본문만 커밋하고 index를 빼먹지 마세요. 다음 작업에서 상태가 맞지 않을 수 있습니다. - 생성이 실패한 뒤 티켓 파일을 손으로 만들거나 frontmatter로 상태를 바로 바꾸지 마세요. - `telemetry.jsonl`은 보통 실행 로그이므로 일반 코드 커밋에는 넣지 않는 편이 낫습니다. - 작업을 마쳤다면 가능하면 `ticket archive`까지 끝낸 뒤 커밋해 active/archive 흐름이 함께 남도록 하세요. 메인테이너와 자동화 환경에서는 `deuk-agent-flow ticket create`, `ticket move`, `ticket archive` 같은 CLI 명령을 직접 사용할 수 있습니다. 자세한 사용 예시는 [docs/usage-guide.ko.md](docs/usage-guide.ko.md)를 참고하세요. --- ## 관련 아이디어와 영감 Deuk Agent Flow는 [andrej-karpathy-skills](https://github.com/forrestchang/andrej-karpathy-skills)처럼 AI 코딩 에이전트가 잘못 가정하고, 과하게 구현하고, 요청 밖 코드를 수정하는 문제의식과 맞닿아 있습니다. 다만 Deuk Agent Flow는 프롬프트 수준의 지침 파일을 넘어 티켓, Phase Gate, 스코프 계약, 검증, 아카이브 가능한 엔지니어링 메모리까지 제공하는 레포 단위 워크플로우 계층입니다. first-party skill MVP는 이 경계를 명확히 유지합니다. skill은 반복 실패 패턴을 다루는 짧은 `SKILL.md` playbook이고, workflow 권한의 단일 기준은 계속 `core-rules/AGENTS.md`입니다. `skill add`와 `skill expose`로 Claude/Cursor에 playbook을 노출하되, 전체 rule contract를 복사하지 않습니다. 스킬 제공 방식: - 스킬 소스는 패키지 `templates/skills/` 단일 진실 공급원에 있으며 `~/.deuk/skills/`(및 `~/.claude/skills/` 같은 네이티브 대상)로 동기화됩니다. - 기본 추천 장착: `safe-refactor`, `generated-file-guard`. - 선택 장착: `context-recall`, `project-pilot`. 현재 first-party skill: | skill | 용도 | |---|---| | `safe-refactor` | 기본 추천: 작은 리팩터링을 범위/테스트 안에 묶기 | | `generated-file-guard` | 기본 추천: generated output 직접 수정 방지 | | `context-recall` | 선택: 과거 티켓/결정/실패 패턴 재사용 | | `project-pilot` | 선택: cross-language, protocol, generated/runtime drift 정리 | | `persona-maid` | 선택: 친절하고 애교 넘치지만 실력은 확실한 메이드 페르소나 (정식 배포 시 기본 비활성, 수동 장착 필요) | ```bash npx deuk-agent-flow init npx deuk-agent-flow skill list npx deuk-agent-flow skill add --skill safe-refactor npx deuk-agent-flow skill add --skill generated-file-guard npx deuk-agent-flow skill add --skill project-pilot npx deuk-agent-flow skill add --skill persona-maid npx deuk-agent-flow skill expose --platform claude ``` --- ### 🏷️ 검색 태그 `#AI-Orchestration` `#Agentic-Workflow` `#DeukFamily` `#Engineering-Intelligence` `#Zero-Legacy` `#High-Signal-Coding` `#AI-Protocol` `#CursorRules` `#CopilotInstructions` `#ClaudeCode` `#ClaudeMD` `#AgentsMD` `#AgentSkills` `#CodingAgent` `#AI-Guardrails` `#LLM-Control-Plane`