DEEPX 에이전트 기반 개발 - dx-agent-dev (베타)
에이전트 기반 개발 지원은 현재 활발히 개발 중입니다. 스킬 정의 및 라우팅 동작은 릴리스 간에 변경될 수 있습니다.
소개
DEEPX 에이전트 기반 개발(dx-agent-dev)이 베타로 출시되었습니다. 자연어로 NPU 앱을 빌드하세요: 앱이나 모델 태스크를 자연어로 설명하면, AI 코딩 에이전트(Claude Code, Cursor, GitHub Copilot, OpenCode 또는 Codex)가 DEEPX 지식 베이스를 end-to-end로 구동합니다 — 브레인스토밍 → 계획 → TDD → 검증, ONNX/.pt 컴파일부터 DX-M1 NPU 디바이스 배포까지. Ultralytics 모델 생태계에서 DEEPX NPU 전용으로 설계된 에이전트 기반 개발이며, 아래의 모든 쇼케이스는 이 방식으로 제작되었습니다 — 프롬프트, 측정 결과, 전체 빌드 트랜스크립트와 함께 저장됩니다.
자연어 명령을 사용하여 DEEPX AI 애플리케이션을 빌드할 수 있습니다. AI 코딩 에이전트는 DEEPX SDK 생태계를 이해합니다 — GStreamer 파이프라인 구성, .dxnn 모델 해석, InferenceEngine 설정, DxPreprocess/DxInfer 요소 연결 등 — 원하는 것을 설명하면 에이전트가 구현 세부 사항을 처리합니다.
지원하는 워크플로우:
IFactory,SyncRunner,AsyncRunner를 사용한 독립형 추론 앱- DEEPX의 6개 카테고리 13개 커스텀 요소를 활용한 GStreamer 비디오 파이프라인
- dx_app, dx_stream, dx-runtime에 걸친 크로스 프로젝트 빌드
- DX-COM(dx-compiler)을 사용한 ONNX에서 DXNN 형식으로의 모델 컴파일
쇼케이스
아래의 모든 쇼케이스는 단 하나의 자연어 프롬프트로 DEEPX NPU SDK를 기반으로 완전 자율적으로 구축된 실제 앱이며, 프롬프트, 측정 결과, 원클릭 재현 방법, 전체 빌드 세션 트랜스크립트와 함께 저장됩니다.
NPU 기반 AI 앱 (미니 게임)
자연어 한 줄로 완전 자율적인 DEEPX-NPU 앱을 ~20분, ~$10에 빌드하세요. 단일 프롬프트로 end-to-end 빌드된 아케이드 HUD 포즈 기반 미니 게임.
| 쇼케이스 | 내용 | 빌드 시간 | 에이전트 턴 | 출력 토큰 | ~비용 |
|---|---|---|---|---|---|
| 스쿼트 카운팅 미니 게임 | 무릎/엉덩이 각도로 스쿼트 횟수를 측정하는 아케이드 HUD (횟수 / 점수 / DOWN·UP·GOOD!). | ≈ 12분 | 132 | ≈ 109K | ≈ $7.3 |
| 스트레칭 코치 미니 게임 | 목표 자세를 시연하는 애니메이션 코치 아바타와 함께 3가지 스트레칭을 안내. | ≈ 15분 | 130 | ≈ 142K | ≈ $8.1 |
Ultralytics 생태계 통합
자연어로 Ultralytics YOLO를 한 번의 명령으로 DEEPX NPU에 올리거나, 도메인에 맞게 재학습하세요. format=deepx 내보내기 + 4방향 평가 (기본/재학습 × fp32-GPU / INT8-NPU); INT8 ≈ fp32, 도메인 모델은 NPU에서 더 빠르게 실행됩니다.
| 쇼케이스 | 내용 | 빌드 시간 | 에이전트 턴 | 출력 토큰 | ~비용 |
|---|---|---|---|---|---|
| Ultralytics YOLO → DeepX 내보내기 | 단일 yolo export ... format=deepx 명령으로 Ultralytics YOLO .pt를 배포 가능한 DeepX NPU 모델(.dxnn)로 변환 후 NPU 추론 + 검증. | ≈ 12분 | 108 | ≈ 84K | ≈ $2.4 |
| 아프리카 야생동물 모니터링 | 사파리/보존 카메라용 african-wildlife(버팔로/코끼리/코뿔소/얼룩말)로 yolo26n 재학습; 기본/재학습 × fp32/INT8 4방향 평가. | ≈ 7분 | 78 | ≈ 85K | ≈ $3.2 |
| 건설 현장 PPE 안전 | 현장 안전 카메라용 construction-ppe(헬멧/조끼/...)로 yolo26n 재학습; 4방향 평가. | ≈ 17분 | 102 | ≈ 93K | ≈ $4.0 |
| 뇌종양 스크리닝 | 의료 엣지 디바이스용 brain-tumor(MRI/CT)로 yolo26n 재학습; 4방향 평가. | ≈ 9분 | 91 | ≈ 103K | ≈ $3.7 |
| 제약 알약 검사 | 제약 계수 스테이션용 medical-pills로 yolo26n 재학습; 4방향 평가. | ≈ 8분 | 118 | ≈ 103K | ≈ $5.1 |
PaddlePaddle 생태계 통합
DEEPX NPU 위의 PaddleOCR (PP-OCRv5) — 단 하나의 간결한 프롬프트로 실시간 비디오 & 웹캠 OCR. DX-M1 NPU에서 실행되는 Baidu PaddlePaddle OCR(텍스트 감지 → 방향 → 인식).
| 쇼케이스 | 내용 | 빌드 시간 | 에이전트 턴 | 출력 토큰 | ~비용 |
|---|---|---|---|---|---|
| 비디오/웹캠 OCR (PP-OCRv5) | DX-M1 NPU에서의 실시간 텍스트 감지 + 인식 — 비디오 파일과 라이브 웹캠을 하나의 코드로, 감지된 박스 + 인식 문자열 오버레이. | ≈ 18분 | 175 | ≈ 184K | ≈ $12.0 |
RapidAI 생태계 통합
단 하나의 간결한 자연어 프롬프트로 DEEPX NPU에서 PDF → 마크다운 문서 변환 앱을 구축. RapidAI의 RapidDoc (PP-StructureV3): 레이아웃, OCR, 표, 수식 — DX-M1 NPU에서 PaddlePaddle 학습 모델 실행.
| 쇼케이스 | 내용 | 빌드 시간 | 에이전트 턴 | 출력 토큰 | ~비용 |
|---|---|---|---|---|---|
| PDF → 마크다운 (문서 변환 앱) | RapidDoc 포크를 통해 DEEPX DX-M1 NPU에서 PDF(디지털 또는 스캔)를 구조화된 마크다운 + JSON으로 변환. `--parse-method auto | txt | ocr` 지원. | ≈ 12분 | 133 |
전체 카탈로그 + 쇼케이스별 요약 (빌드 GIF 포함) →
dx-agent-dev-showcase/README.md. 각 행의 링크를 클릭하면 해당 쇼케이스의 README — 그대로의 프롬프트, 4방향 평가/게임플레이 세부 정보, 세션 트랜스크립트 — 가 열립니다.
동작 원리 — 모델뿐만 아니라 하니스
각 앱에는 완전한 에이전트 세션 트랜스크립트가 포함됩니다. 이는 결과가 단순한 모델 성능보다 하니스가 부과하는 명령 지침, 스킬, 검증 게이트에 더 의존한다는 것을 직접 확인하는 가장 좋은 방법입니다. 트랜스크립트를 읽으면서 다음을 확인할 수 있습니다:
- 명령 준수 — 에이전트가 스위트 HARD GATES를 준수: 세션 센티넬(
[DX-AGENT-DEV: START]/DONE), 세션 디렉토리에 격리된 출력(기존 소스 미수정), 플레이스홀더/스텁 코드 금지. - 스킬 및 에이전트 활용 — 필수 시퀀스를 실제 도구 호출로 수행 —
dx-skill-router → dx-agent-brainstorm → dx-swe-writing-plans → dx-agent-tdd → dx-agent-verify— 단순히 언급하는 것이 아닌 실제 실행. - 실제 추론 — 가장 유사한 기존 예제 검토, 지식 베이스에서 실제 프레임워크 API 확인, 검증 먼저 작성(RED), 완료 선언 전 파일별 생성 + 검증.
사전 요구 사항
| 요구 사항 | 세부 내용 |
|---|---|
| DEEPX 개발 환경 | DX-RT SDK 설치 및 setup_env.sh 소스 완료 |
| AI 코딩 에이전트 (다음 중 하나) | Claude Code, GitHub Copilot (VS Code), Cursor, OpenCode, 또는 Codex CLI |
| Python | dx-all-suite 패키지가 설치된 3.10+ |
아키텍처 개요
에이전트 기반 지식 베이스는 세 개의 독립적인 레이어로 구성됩니다. 각 레이어는 에이전트가 태스크 실행 시 읽는 스킬, 명령, 메모리 파일을 포함하는 자체 .deepx/ 디렉토리를 갖습니다.
dx_app — 독립형 추론
GStreamer 없이 추론을 실행하는 Python 및 C++ 애플리케이션. 핵심 추상화:
- IFactory — 모델별 전/후처리 파이프라인 생성
- SyncRunner / AsyncRunner — 블로킹 및 논블로킹 추론 실행기
- DxInfer — InferenceEngine을 감싸는 저수준 추론 래퍼
.deepx/ 지식 베이스는 모델 로딩, .dxnn 해석, 배치 처리, 결과 시각화를 다룹니다.
dx_stream — GStreamer 파이프라인
GStreamer 기반의 실시간 비디오 분석. 에이전트는 6개 기능 카테고리(소스, 추론, 오버레이, 인코딩, 스트리밍, 싱크)로 구성된 13개 DEEPX 요소를 모두 이해하며, 단일 자연어 프롬프트로 다중 분기 파이프라인을 조립할 수 있습니다.
dx-runtime — 통합 레이어
크로스 프로젝트 라우팅 및 통합 검증. dx-runtime은 다른 두 레이어 위에 위치하며, 올바른 서브 프로젝트 빌더로 태스크를 디스패치하고 일관된 코딩 표준, 테스트 패턴, 모델 관리 규칙을 적용합니다.
dx-compiler — 모델 컴파일
DX-COM으로 구동되는 DXNN 모델 컴파일. 에이전트는 전체 컴파일 파이프라인을 이해합니다 — ONNX 모델 검증, 자동 추론 파라미터를 포함한 config.json 생성, 캘리브레이션 데이터 준비, INT8 양자화, PPU 설정 — 단일 자연어 프롬프트로 모델을 컴파일할 수 있습니다. 컴파일 전, 에이전트는 NMS-free 모델 감지, ONNX 단순화, PPU 컴파일에 관한 필수 브레인스토밍 질문을 통해 올바른 설정을 보장합니다.
사용 가능한 에이전트 및 스킬
에이전트와 스킬은 레포지토리의 모든 레벨에서 사용 가능합니다. 최상위 dx-all-suite는 태스크를 분류하고 올바른 서브모듈로 디스패치하는 라우팅 에이전트를 제공합니다.
레벨별 에이전트
| 레벨 | 에이전트 | 설명 |
|---|---|---|
| dx-all-suite | @dx-suite-builder | 최상위 라우터 — 태스크를 분류하고 적절한 서브모듈로 라우팅 |
| dx-all-suite | @dx-suite-validator | 스위트 전체 검증 — 3개 레벨에 걸친 프레임워크 검사 실행 |
| dx-runtime | @dx-runtime-builder | 크로스 프로젝트 빌더 — dx_app 또는 dx_stream으로 라우팅 |
| dx-runtime | @dx-validator | 피드백 루프를 포함한 통합 검증 오케스트레이터 |
| dx_app | @dx-app-builder | 독립형 추론 빌더 — 전문 빌더로 라우팅 |
| dx_app | @dx-python-builder | Python 추론 앱 빌더 (4가지 변형: sync, async, cpp_postprocess, async_cpp_postprocess) |
| dx_app | @dx-cpp-builder | C++ 추론 앱 빌더 |
| dx_app | @dx-model-manager | 모델 다운로드 및 레지스트리 관리자 |
| dx_app | @dx-validator | dx_app 검증 및 피드백 루프 |
| dx_stream | @dx-stream-builder | GStreamer 파이프라인 빌더 — 전문 빌더로 라우팅 |
| dx_stream | @dx-pipeline-builder | 파이프라인 구성 (브로커 포함 6개 카테고리) |
| dx_stream | @dx-validator | dx_stream 검증 및 피드백 루프 |
| dx-compiler | @dx-compiler-builder | 모델 컴파일 라우터 — 변환기 또는 컴파일러로 라우팅 |
| dx-compiler | @dx-model-converter | PyTorch에서 ONNX 모델 변환기 |
| dx-compiler | @dx-dxnn-compiler | ONNX에서 DXNN 컴파일러 (DX-COM) |
스킬 (OpenCode 전용)
| 레벨 | 스킬 | 설명 |
|---|---|---|
| dx-runtime | /dx-agent-runtime-validate | 검증, 피드백 수집, 수정 적용, 재검증 |
| dx_app | /dx-agent-app-build-python | Python 추론 앱 빌드 |
| dx_app | /dx-agent-app-build-cpp | C++ 추론 앱 빌드 |
| dx_app | /dx-agent-app-build-async | 비동기 고성능 앱 빌드 |
| dx_app | /dx-agent-app-model-management | 모델 다운로드 및 설정 |
| dx_app | /dx-agent-app-validate | 검증 검사 실행 |
| dx_stream | /dx-agent-stream-build-pipeline | GStreamer 파이프라인 앱 빌드 |
| dx_stream | /dx-agent-stream-build-mqtt-kafka | MQTT/Kafka 파이프라인 앱 빌드 |
| dx_stream | /dx-agent-stream-validate | 검증 검사 실행 |
| dx_stream | /dx-agent-stream-model-management | 모델 다운로드 및 설정 |
| dx-compiler | /dx-agent-compiler-convert | PyTorch 모델을 ONNX로 변환 |
| dx-compiler | /dx-agent-compiler-compile | ONNX 모델을 DXNN으로 컴파일 |
| dx-compiler | /dx-agent-compiler-validate | 컴파일된 DXNN 출력 검증 |
| DX All Suite | /dx-swe-brainstorm | 프로세스: 작업 전 협업 설계 세션 |
| DX All Suite | /dx-swe-tdd | 프로세스: 테스트 주도 개발 — 증분 검증 |
| DX All Suite | /dx-swe-verify | 프로세스: 완료 선언 전 검증 — 주장 전 증거 |
| dx-runtime | /dx-swe-brainstorm | 프로세스: 코드 생성 전 협업 설계 세션 |
| dx-runtime | /dx-swe-tdd | 프로세스: 테스트 주도 개발 — 파일 생성 즉시 검증 |
| dx-runtime | /dx-swe-verify | 프로세스: 완료 선언 전 검증 — 주장 전 증거 |
| dx_app | /dx-swe-brainstorm | 프로세스: 코드 생성 전 협업 설계 세션 |
| dx_app | /dx-swe-tdd | 프로세스: 테스트 주도 개발 — 파일 생성 즉시 검증 |
| dx_app | /dx-swe-verify | 프로세스: 완료 선언 전 검증 — 주장 전 증거 |
| dx_stream | /dx-swe-brainstorm | 프로세스: 코드 생성 전 협업 설계 세션 |
| dx_stream | /dx-swe-tdd | 프로세스: 테스트 주도 개발 — 파일 생성 즉시 검증 |
| dx_stream | /dx-swe-verify | 프로세스: 완료 선언 전 검증 — 주장 전 증거 |
| dx-compiler | /dx-swe-brainstorm | 프로세스: 컴파일 전 협업 설계 세션 |
| dx-compiler | /dx-swe-tdd | 프로세스: 테스트 주도 개발 — 각 단계 증분 검증 |
| dx-compiler | /dx-swe-verify | 프로세스: 완료 선언 전 검증 — 주장 전 증거 |
어떤 서브모듈을 타겟팅해야 할지 모를 경우, 최상위 레벨에서 @dx-suite-builder를 사용하세요 — 태스크를 분류하고 올바른 빌더로 자동 라우팅합니다.
지원하는 AI 도구
에이전트 기반 개발은 5가지 AI 코딩 도구와 함께 작동합니다. 각 도구는 자체 설정 메커니즘을 통해 .deepx/ 지식 베이스를 자동으로 로드합니다.
| 도구 | 유형 | 자동 로드 메커니즘 | 에이전트 호출 | 스킬 호출 |
|---|---|---|---|---|
| Claude Code | CLI | 프로젝트 루트의 CLAUDE.md | 자유 형식 대화; Context Routing Table이 자동 디스패치 | — |
| GitHub Copilot | VS Code | .github/copilot-instructions.md | Copilot Chat에서 @agent-name "prompt" | — |
| Cursor | IDE | .cursor/rules/*.mdc | 자유 형식 대화; alwaysApply 또는 globs로 규칙 로드 | — |
| OpenCode | CLI | AGENTS.md + opencode.json | @agent-name "prompt" | /skill-name 슬래시 명령 |
| Codex CLI | CLI | AGENTS.md + .codex/skills/dx-codex-identity/SKILL.md | 자유 형식 대화 (~/bin/codex exec ...) | cat .deepx/skills/<name>/SKILL.md (직접 읽기) |
자동 로드 항목
| 도구 | 전역 컨텍스트 | 파일별 컨텍스트 | 에이전트 | 스킬 |
|---|---|---|---|---|
| Claude Code | CLAUDE.md | Context Routing Table (수동) | .claude/agents/*.md (생성됨) | .deepx/skills/ (직접 읽기) |
| Copilot | .github/copilot-instructions.md | .github/instructions/*.instructions.md (applyTo: glob) | .github/agents/*.agent.md | .github/skills/ (인라인 복사본) |
| Cursor | .cursor/rules/dx-*.mdc (alwaysApply: true) | .cursor/rules/*.mdc (globs: [...]) | .cursor/rules/ 에이전트 .mdc 파일 | .cursor/rules/ 스킬 .mdc 파일 |
| OpenCode | AGENTS.md + opencode.json 명령 | — | .opencode/agents/*.md | .deepx/skills/*/SKILL.md |
| Codex CLI | AGENTS.md | — | .deepx/agents/*.md (직접 cat) | .codex/skills/dx-codex-identity/ (자동) + .deepx/skills/ (수동 cat) |
최초 설정
추가 설정이 필요 없습니다. 원하는 도구에서 프로젝트 디렉토리를 열면 설정 파일이 자동으로 로드됩니다:
# Claude Code
cd dx-all-suite
claude
# OpenCode
cd dx-all-suite
opencode
# Codex CLI
cd dx-all-suite
~/bin/codex
# GitHub Copilot — VS Code에서 폴더 열기
code dx-all-suite
# Cursor CLI
cd dx-all-suite
cursor-agent
플랫폼 파일 로딩 참고
각 AI 코딩 에이전트는 스위트 레벨에서 서로 다른 설정 파일을 자동 로드합니다. 자동 표시 파일은 모든 대화에서 로드되며, @mention 파일은 에이전트 또는 스킬 명령으로 수동 호출합니다.
Copilot Chat/CLI, Claude Code, Codex CLI는 현재 git 루트의 파일만 볼 수 있습니다. dx-all-suite/에서 열면 dx-compiler/, dx-runtime/ 등 서브 프로젝트 파일을 자동으로 로드하지 않습니다(별도의 git 서브모듈). OpenCode는 opencode.json의 명시적 경로 참조를 통해 이 경계를 넘습니다.
자동 로드 파일
| 파일 | 자동 로드 도구 | 로딩 방식 |
|---|---|---|
.github/copilot-instructions.md | Copilot Chat/CLI | 자동 |
CLAUDE.md | Claude Code | 자동 |
AGENTS.md + opencode.json | OpenCode | 자동 |
AGENTS.md + .codex/skills/dx-codex-identity/SKILL.md | Codex CLI | 자동 |
.cursor/rules/dx-all-suite.mdc | Cursor | 자동 |
에이전트 파일 (수동 @mention)
| 에이전트 | Copilot (@mention) | OpenCode (@mention) |
|---|---|---|
dx-suite-builder | .github/agents/dx-suite-builder.agent.md | .opencode/agents/dx-suite-builder.md |
dx-suite-validator | .github/agents/dx-suite-validator.agent.md | .opencode/agents/dx-suite-validator.md |
Claude Code는 .claude/agents/에 생성된 에이전트 파일(예: dx-suite-builder.md)이 있습니다.
Cursor는 .cursor/rules/에 에이전트 .mdc 파일(예: dx-suite-builder.mdc)이 있습니다.
Claude Code는 CLAUDE.md의 Context Routing Table을 사용하여 태스크를 디스패치합니다.
스킬 파일 (OpenCode 전용 — /슬래시-명령)
| 스킬 | 파일 |
|---|---|
/dx-swe-brainstorm | .deepx/skills/dx-swe-brainstorm/SKILL.md |
/dx-swe-verify | .deepx/skills/dx-swe-verify/SKILL.md |
/dx-swe-tdd | .deepx/skills/dx-swe-tdd/SKILL.md |
/dx-swe-parallel-agents | .deepx/skills/dx-swe-parallel-agents/SKILL.md |
/dx-swe-executing-plans | .deepx/skills/dx-swe-executing-plans/SKILL.md |
/dx-swe-receiving-review | .deepx/skills/dx-swe-receiving-review/SKILL.md |
/dx-swe-requesting-review | .deepx/skills/dx-swe-requesting-review/SKILL.md |
/dx-skill-router | .deepx/skills/dx-skill-router/SKILL.md |
/dx-swe-subagent-dev | .deepx/skills/dx-swe-subagent-dev/SKILL.md |
/dx-swe-debugging | .deepx/skills/dx-swe-debugging/SKILL.md |
/dx-swe-writing-plans | .deepx/skills/dx-swe-writing-plans/SKILL.md |
공유 지식 베이스 (.deepx/)
.deepx/ 디렉토리는 모든 플랫폼별 파일의 정식 소스(단일 진실 소스)입니다. 플랫폼에 독립적인 형식으로 에이전트, 스킬, 템플릿, 프래그먼트를 포함합니다. dx-agent-gen 생성기가 이를 Copilot(.github/), Claude Code(.claude/), OpenCode(.opencode/), Cursor(.cursor/rules/)용 플랫폼별 파일로 변환합니다.
| 디렉토리 | 내용 |
|---|---|
agents/ | dx-suite-builder, dx-suite-validator |
skills/ | 13개 스킬 (도메인 + 공유 프로세스 스킬) |
templates/ | {en,ko}/*.tmpl — 명령 파일 템플릿 |
templates/fragments/ | {en,ko}/*.md — 레포 전반에 재사용되는 공유 섹션 |
memory/ | 세션 간 지속되는 지식 |
knowledge/ | 구조화된 참조 데이터 |
instructions/ | 내부 에이전트 명령 |
toolsets/ | 도구 참고 문서 |
명령 파일(CLAUDE.md, AGENTS.md, copilot-instructions.md, EN+KO)도 템플릿과 프래그먼트에서 생성됩니다 — 직접 편집하지 마세요.
플랫폼 파일 생성
모든 플랫폼별 파일은 dx-agent-dev-gen 패키지로 .deepx/에서 생성됩니다. 생성된 파일을 직접 편집하지 마세요.
pip install -e .deepx/tools # 생성기 설치
dx-agent-gen generate # 플랫폼 파일 생성
dx-agent-gen check # 드리프트 없음 확인
Pre-commit 훅이 생성된 파일의 동기화를 강제합니다:
.deepx/tools/scripts/install-hooks.sh # 1회 설정
도구별 빠른 시작
dx-all-suite에서 (최상위 라우팅)
최상위 dx-all-suite 디렉토리에서 작업하며 에이전트가 올바른 서브모듈로 자동 라우팅하게 하려면:
프롬프트:
"yolo26n.onnx를 DXNN으로 컴파일하고 이를 사용한 사람 감지 Python 앱을 빌드해줘"
| 도구 | 사용 방법 |
|---|---|
| Claude Code | dx-all-suite/를 열고 프롬프트를 입력하세요. CLAUDE.md가 컴파일은 dx-compiler로, 앱 생성은 dx_app으로 라우팅합니다. |
| GitHub Copilot | Copilot Chat 열기: @dx-suite-builder와 프롬프트. 에이전트가 태스크를 분류하고 올바른 서브모듈로 라우팅합니다. |
| Cursor | dx-all-suite/를 열고 프롬프트를 입력하세요. alwaysApply 규칙이 적절한 서브모듈로 라우팅합니다. |
| OpenCode | dx-all-suite/를 열고: @dx-suite-builder와 프롬프트. 에이전트가 자동으로 라우팅합니다. |
| Codex CLI | dx-all-suite/를 열고 프롬프트 입력(또는 ~/bin/codex exec "<prompt>"). AGENTS.md가 자동으로 읽히고 서브모듈 간 라우팅합니다. |
서브모듈에서 (직접 접근)
서브모듈에서 직접 작업할 때는 해당 서브모듈의 범위에 맞는 프롬프트를 사용하세요:
| 서브모듈 | 예시 프롬프트 |
|---|---|
| dx-compiler | "yolo26x.pt를 ONNX로 변환하고 DX-M1용 DXNN으로 컴파일해줘" |
| dx_app | "Python을 사용한 yolo26n 사람 감지 앱을 빌드해줘" |
| dx_stream | "RTSP 카메라와 트래킹이 있는 감지 파이프라인을 빌드해줘" |
| 도구 | 사용 방법 |
|---|---|
| Claude Code | 서브모듈 디렉토리를 열고 프롬프트를 직접 입력하세요. CLAUDE.md가 자동으로 읽힙니다. Context Routing Table이 올바른 .deepx/ 스킬 파일로 디스패치합니다. |
| GitHub Copilot | Copilot Chat 열기: @dx-app-builder, @dx-stream-builder, 또는 @dx-compiler-builder와 프롬프트. Copilot은 모든 채팅에서 .github/copilot-instructions.md를 읽습니다. |
| Cursor | 서브모듈 폴더를 열고 프롬프트를 직접 입력하세요. alwaysApply: true인 규칙이 모든 대화에서 로드됩니다. globs: 패턴이 있는 규칙은 매칭 파일 편집 시 활성화됩니다. |
| OpenCode | 서브모듈 디렉토리를 열고 적절한 에이전트(@dx-app-builder, @dx-stream-builder, 또는 @dx-compiler-builder) 또는 해당 스킬 슬래시 명령을 사용하세요. |
| Codex CLI | 서브모듈 디렉토리를 열고 프롬프트 입력(또는 ~/bin/codex exec "<prompt>"). AGENTS.md가 자동으로 읽히며, 필요 시 .deepx/skills/<name>/SKILL.md를 직접 cat하세요. |
End-to-End 시나리오
여러 서브모듈에 걸친 크로스 프로젝트 워크플로우 시나리오입니다. 서브 프로젝트별 시나리오는 아래 링크된 개별 가이드를 참고하세요.
시나리오 1: 커스텀 모델 변환 + SDK 포팅 + 검증
커스텀 모델을 컴파일하고, 추론 코드를 DEEPX SDK로 포팅하고, 결과를 검증하는 전체 파이프라인.
프롬프트:
"./models/에 yolo26x-custom.onnx가 있고 onnxruntime을 사용하는 추론 코드가 ./inference.py에 있어. DXNN으로 변환하고 내 코드를 DEEPX SDK로 포팅해줘."
| 도구 | 사용 방법 |
|---|---|
| Claude Code | dx-all-suite/를 열고 프롬프트를 입력하세요. 스위트 빌더가 오케스트레이션합니다: (a) dx-compiler가 ONNX 모델을 DXNN으로 컴파일, (b) dx_app이 추론 코드 포팅, (c) 검증으로 포팅된 앱 동작 확인. |
| GitHub Copilot | @dx-suite-builder와 프롬프트. 에이전트가 컴파일은 dx-compiler로, 포팅은 dx_app으로 라우팅합니다. |
| Cursor | dx-all-suite/를 열고 프롬프트를 입력하세요. 라우터가 올바른 서브모듈로 디스패치합니다. |
| OpenCode | @dx-suite-builder와 프롬프트. |
| Codex CLI | dx-all-suite/를 열고 프롬프트를 입력하세요. AGENTS.md가 크로스 서브모듈 작업을 오케스트레이션합니다. |
3단계로 진행됩니다:
- dx-compiler: 자동 추론 config로
yolo26x-custom.onnx→yolo26x-custom.dxnn컴파일 - dx_app: 컴파일된 모델을 사용하는
InferenceEnginePython 추론 앱 생성 - 검증: 포팅된 앱 실행 후 원본 onnxruntime 코드와 출력 비교
시나리오 2: 모델 컴파일 + 샘플 앱 생성
모델을 컴파일하고 컴파일된 출력을 사용하는 독립형 추론 앱을 생성합니다. dx-compiler와 dx_app에 걸친 크로스 프로젝트 시나리오.
프롬프트:
"yolo26n.onnx를 DXNN으로 컴파일하고 컴파일된 모델을 사용하는 Python 감지 앱을 생성해줘"
| 도구 | 사용 방법 |
|---|---|
| Claude Code | dx-all-suite/를 열고 프롬프트를 입력하세요. 스위트 빌더가 오케스트레이션합니다: (a) dx-compiler가 ONNX를 DXNN으로 컴파일, (b) dx_app이 컴파일된 모델을 참조하는 Python 앱 생성. |
| GitHub Copilot | @dx-suite-builder와 프롬프트. 컴파일은 dx-compiler로, 앱 생성은 dx_app으로 라우팅. |
| Cursor | dx-all-suite/를 열고 프롬프트를 입력하세요. 라우터가 두 서브모듈로 디스패치합니다. |
| OpenCode | @dx-suite-builder와 프롬프트. |
| Codex CLI | dx-all-suite/를 열고 프롬프트를 입력하세요. AGENTS.md가 크로스 서브모듈 작업을 오케스트레이션합니다. |
2단계로 진행됩니다:
- dx-compiler: 자동 추론 config로
yolo26n.onnx→yolo26n.dxnn컴파일 - dx_app: 컴파일된
.dxnn모델을 사용하는 Python 감지 앱 생성
시나리오 3: 모델 컴파일 + 스트리밍 파이프라인 생성
모델을 컴파일하고 컴파일된 출력을 사용하는 GStreamer 스트리밍 파이프라인을 생성합니다. dx-compiler와 dx_stream에 걸친 크로스 프로젝트 시나리오.
프롬프트:
"yolo26n.onnx를 DXNN으로 컴파일하고 RTSP 출력이 있는 감지 스트리밍 파이프라인을 빌드해줘"
| 도구 | 사용 방법 |
|---|---|
| Claude Code | dx-all-suite/를 열고 프롬프트를 입력하세요. 스위트 빌더가 오케스트레이션합니다: (a) dx-compiler가 ONNX를 DXNN으로 컴파일, (b) dx_stream이 RTSP 출력 GStreamer 파이프라인 생성. |
| GitHub Copilot | @dx-suite-builder와 프롬프트. 컴파일은 dx-compiler로, 파이프라인은 dx_stream으로 라우팅. |
| Cursor | dx-all-suite/를 열고 프롬프트를 입력하세요. 라우터가 두 서브모듈로 디스패치합니다. |
| OpenCode | @dx-suite-builder와 프롬프트. |
| Codex CLI | dx-all-suite/를 열고 프롬프트를 입력하세요. AGENTS.md가 크로스 서브모듈 작업을 오케스트레이션합니다. |
2단계로 진행됩니다:
- dx-compiler: 자동 추론 config로
yolo26n.onnx→yolo26n.dxnn컴파일 - dx_stream: 컴파일된 모델을 DxInfer로 사용하고 RTSP 스트리밍 출력을 포함한 감지 파이프라인 생성
시나리오 4: PPU 모델 컴파일 + 감지 앱
PPU(전/후처리 장치) 지원으로 모델을 컴파일하여 하드웨어 가속 후처리를 적용하고, PPU 모델을 사용하는 앱을 생성합니다.
프롬프트:
"yolo26n.onnx를 PPU 지원으로 컴파일하고 PPU 모델용 감지 앱을 생성해줘"
| 도구 | 사용 방법 |
|---|---|
| Claude Code | dx-all-suite/를 열고 프롬프트를 입력하세요. 스위트 빌더가 오케스트레이션합니다: (a) dx-compiler가 PPU config로 컴파일(YOLO 버전 기반 자동 감지), (b) dx_app이 단순화된 후처리를 포함한 PPU 전용 앱 생성. |
| GitHub Copilot | @dx-suite-builder와 프롬프트. PPU 컴파일은 dx-compiler로, PPU 앱 생성은 dx_app으로 라우팅. |
| Cursor | dx-all-suite/를 열고 프롬프트를 입력하세요. 라우터가 두 서브모듈로 디스패치합니다. |
| OpenCode | @dx-suite-builder와 프롬프트. |
| Codex CLI | dx-all-suite/를 열고 프롬프트를 입력하세요. AGENTS.md가 크로스 서브모듈 작업을 오케스트레이션합니다. |
2단계로 진행됩니다:
- dx-compiler: PPU config로 컴파일 — 에이전트가 PPU 타입을 자동 감지(앵커 기반 YOLO는 Type 0, 앵커 프리 YOLO는 Type 1)
- dx_app: 하드웨어로 디코딩된 바운딩 박스를 포함한 단순화된 후처리로
src/python_example/ppu/하위에 PPU 전용 감지 앱 생성
크로스 프로젝트 라우팅
dx-all-suite 메타 가이드는 모든 서브 프로젝트 시나리오로의 라우팅을 제공합니다. 태스크가 서브 프로젝트 가이드의 시나리오와 일치하면 스위트 빌더가 자동으로 라우팅합니다.
- dx-runtime 시나리오 (크로스 프로젝트 빌드, 통합 검증): dx-runtime 가이드 참고
- dx_app 시나리오 (Python/C++ 추론 앱): dx_app 가이드 참고
- dx_stream 시나리오 (GStreamer 파이프라인): dx_stream 가이드 참고
- dx-compiler 시나리오 (모델 컴파일): dx-compiler 가이드 참고
서브 프로젝트 디렉토리로 이동할 필요가 없습니다. dx-all-suite 레벨에서 @dx-suite-builder를 사용하면 어떤 서브 프로젝트로도 자동 라우팅됩니다.
서브 프로젝트 가이드
각 서브 프로젝트는 특정 스킬, 요소 카탈로그, 실제 예제를 다루는 상세한 에이전트 기반 개발 가이드를 제공합니다:
내부 참고 문서
기여자를 위한 .deepx/ 정식 소스, 생성기 파이프라인, 하니스 개발 모델의 심층 내용(최종 사용자 대상 아님):
| 문서 | 범위 |
|---|---|
.deepx/docs/dx-agent-dev-overview.md | 5개 레포 전체의 모든 .deepx/ 디렉토리 상세 설명 |
.deepx/README.md | .deepx/ 지식 베이스 최상위 마스터 인덱스 |
.deepx/docs/skill-architecture.md | 3단계 스킬 모델 (SWE / 에이전트 기반 / 하니스) |
.deepx/tools/README.md | dx-agent-gen 생성기 패키지 가이드 |
.deepx/tools/scripts/README.md | 운영 스크립트 (run_all.sh, 훅, E2E 루프) |
출력 격리
기본적으로 에이전트가 생성한 모든 코드는 타겟 서브 프로젝트 내 dx-agent-dev/<session_id>/에 저장됩니다. 기존 프로덕션 코드의 우발적 수정을 방지합니다.
| 출력 유형 | 경로 | 조건 |
|---|---|---|
| 기본 (격리) | dx-agent-dev/<session_id>/ | 사용자가 별도 지정 없으면 항상 |
| 프로덕션 | src/ | 사용자가 명시적으로 요청한 경우만 |
세션 ID 형식: YYYYMMDD-HHMMSS_<agent>_<model>_<task> (여기서 <agent>는 claude, codex, copilot, cursor, opencode).
각 세션 디렉토리에는 다음이 포함됩니다:
README.md— 세션 메타데이터, 생성 파일 목록, 실행 방법session.json— 기계 판독 가능한 세션 설정
dx-agent-dev/ 디렉토리는 dx_app과 dx_stream 모두에서 git-ignore됩니다.
dx-compiler 세션 디렉토리
dx-compiler의 경우, 세션 디렉토리에 추가로 다음이 포함됩니다:
calibration_dataset—dx_com/calibration_dataset/의 심볼릭 링크config.json— 상대 캘리브레이션 경로가 포함된 자동 생성 DX-COM configcompiler.log— 컴파일 로그(--gen_log사용 시)
에이전트는 캘리브레이션 데이터를 자동으로 설정합니다(dx_com/calibration_dataset/ 확인, 필요 시 설정 스크립트 실행, 상대 경로로 심볼릭 링크 생성).
스위트 레벨 크로스 프로젝트 출력
dx-all-suite 레벨에서 크로스 프로젝트 태스크(예: 컴파일 + 배포)를 실행할 때, 아티팩트는 각 타겟 서브 프로젝트의 dx-agent-dev/ 디렉토리에 생성됩니다. 통합 접근을 위해 dx-all-suite/dx-agent-dev/에도 심볼릭 링크가 생성됩니다:
dx-all-suite/dx-agent-dev/
├── dx-compiler_20260409-070940_yolo26n_pt_to_dxnn -> ../dx-compiler/dx-agent-dev/20260409-...
└── dx_app_20260409-071500_yolo26n_detection_app -> ../dx-runtime/dx_app/dx-agent-dev/20260409-...
심볼릭 링크 명명 규칙: {subproject}_{session_id}.
세션 센티넬
에이전트는 자동화 테스트를 위해 각 태스크의 시작과 끝에 고정 마커를 출력합니다:
| 마커 | 조건 |
|---|---|
[DX-AGENT-DEV: START] | 필수 — 다른 텍스트, 도구 호출, 추론보다 먼저 에이전트 첫 번째 응답의 절대 첫 줄. "그냥 진행해"라고 해도 생략 불가 — 이 마커 없이는 자동화 테스트가 실패합니다. |
[DX-AGENT-DEV: DONE (output-dir: <relative_path>)] | 모든 작업 완료 후 마지막 줄. <relative_path>는 프로젝트 루트 기준 세션 출력 디렉토리. 파일이 생성되지 않은 경우 (output-dir: ...) 부분 생략. |
중요: DONE은 모든 결과물이 생성됨을 의미합니다 — 구현 코드, 스크립트, config, 검증 결과. 실제 코드 구현 없이 계획 아티팩트(스펙, 계획, 설계 문서)만 생성한 경우 DONE을 출력하면 안 됩니다.