WorkNaru는 다양한 AI 기반 업무 기능을 Module로 추가하고 조합할 수 있는 확장 가능한 AI Workspace입니다.
사용자는 하나의 Workspace 안에서 AI 에이전트, 도구, 파일과 상호작용하며 작업합니다. 필요한 업무 서비스는 독립적인 Module을 통해 확장하며, 플랫폼은 특정 업무 영역이나 문서 처리에 종속되지 않습니다.
Windows에서 Node.js 24.18 이상 24.x, PowerShell 7, Codex CLI와 기존 로그인을 준비하고 저장소 루트에서 실행합니다. Paseo의 native 패키지 설치 script를 허용해야 합니다.
npm ci --cache .npm-cache # 최초 설치 또는 의존성 변경 시
npm run dev최신 코드를 빌드하고 전용 runtime·WorkNaru Daemon·Vite를 시작한 뒤 브라우저를 엽니다. 기본 UI는 http://127.0.0.1:15173, 제품 Daemon은 ws://127.0.0.1:4310/ws이며 화면은 자동 연결됩니다. 포트가 사용 중이면 npm run dev -- --web-port 15175 --daemon-port 14310처럼 변경합니다.
UI 소스 변경은 자동 반영됩니다. Daemon 코드를 바꾸면 Ctrl+C로 종료한 뒤 다시 실행합니다. dev:web과 preview:web은 UI만 실행하므로 별도 Daemon 연결이 필요합니다. 명령별 차이와 두 터미널에서 실행하는 예제는 개발 안내를 참고하세요.
새 Chat에서 모델·추론 강도를 고르고 첫 입력과 후속 질문을 보낼 수 있습니다. Codex 도구 실행, 추가 권한의 1회 허용·거절, 취소와 새 기록의 재시작 조회를 제공합니다. Workspace 안의 파일 수정은 기본 허용하며 추가 권한이 필요한 작업만 요청 시 승인합니다.
왼쪽 설정에서 화면 배색, 연결 상태, 새 대화 기본 모델·추론 강도를 조절합니다. AI 기본값은 Daemon에 저장되어 재시작 후에도 유지되며 기존 대화의 선택은 바뀌지 않습니다. 좁은 화면은 목록 복귀 버튼을 통해 Module 선택·대화 목록·설정을 오갑니다. 대화와 설정을 오가는 동안 초안과 읽던 위치를 유지합니다.
종료는 실행 터미널의 Ctrl+C입니다. 진행 중인 작업을 중단하고 이번 실행이 소유한 runtime과 서버를 정리합니다. 탭 닫기·새로고침·호출 도구 종료는 제품 실행을 끝내지 않습니다.
제품은 .worknaru-dev/paseo-v1의 새 데이터에서 시작합니다. 전용 Paseo·Codex home을 사용하며 개인 Codex 로그인 자료만 복사합니다. 구형 ACP 대화·파일 승인 기록은 읽거나 이식하지 않습니다. 기존 Workspace의 실제 파일은 그대로 사용합니다. 로그인·계정 전환, 기존 운영 CLI·Hub 공유는 제공하지 않습니다. 설정의 연결 상태와 Provider 인증 여부는 구분하며, 현재 인증 상태는 별도 확인할 수 없습니다.
| 목적 | 명령 |
|---|---|
| 실행·UI 점검 | npm run dev |
| 타입 검사 | npm run typecheck |
| 빌드와 제품 동작 시험 | npm test |
| 브라우저 전체 시험(동작·시각 기준) | npm run test:web |
| 브라우저 동작 시험 | npm run test:web:behavior |
| 고정 환경의 시각 기준 시험 | npm run test:web:visual |
| UI 없는 계약·runtime 시험 | npm run test:daemon |
브라우저 동작 시험에는 Windows와 Edge가 필요합니다. 시각 시험은 기준 환경과 갱신 안내의 OS·Edge·폰트 조건까지 일치해야 합니다.
npm run build:daemon
npm start -- --workspace . --data-dir .worknaru-dev/paseo-v1다른 터미널에서 npm run rpc를 실행하면 같은 Daemon의 연결 상태를 조회합니다. JSON 요청 파일로 대화 생성·입력·설정·승인·취소도 호출할 수 있습니다. UI가 필요하면 npm run build 후 npm start -- --web-ui를 실행하고 http://127.0.0.1:4310/을 엽니다.
--codex-path 또는 WORKNARU_CODEX_PATH로 executable을 지정할 수 있으며, 생략하면 PATH의 codex.exe를 사용합니다. 설치·개별 실행·protocol 2 호출 예제·결과 불명 처리·실제 AI 검증·복귀 절차는 로컬 개발 안내를 따릅니다.
WorkNaru는 공통 작업 환경과 실행 기반을 제공하는 플랫폼과 실제 업무 서비스를 제공하는 Module로 구성됩니다. 이 절에서 제품의 핵심 개념과 책임 경계를 정의합니다. 선택의 근거와 영향은 ADR-0006에 기록합니다.
플랫폼은 Module이 함께 사용하는 작업 환경과 공통 실행 기능을 제공하는 기반입니다. 공통 기반에는 다음과 같은 역할이 포함될 수 있습니다.
- Workspace 관리
- AI 에이전트 연결, 세션과 실행 관리
- 도구 실행과 사용자 권한 승인
- 파일·결과물의 저장과 접근을 위한 공통 기능
- 실행 상태와 기록의 관리·전달
- 공통 설정과 Module 등록·사용을 위한 기능
이 목록은 처음부터 모두 구현해야 할 기능 명세가 아닙니다. 실제 Module을 만들고 검증하는 과정에서 필요한 공통 기반을 점진적으로 갖춥니다. 초기 Workspace는 폴더를 기준으로 하며, 별도의 Project 계층은 아직 정의하지 않습니다. Workspace 결정
Module은 WorkNaru의 공통 기반 위에서, 특정 업무 목적을 달성하기 위한 사용자 경험·업무 규칙·데이터·처리 흐름을 소유하고, 사용자가 확인하거나 활용할 수 있는 결과를 제공하는 독립적인 업무 서비스 단위입니다.
독립적이라는 뜻은 업무 책임을 구분하고 별도로 발전시킬 수 있다는 의미입니다. 별도 서버·프로세스·저장소·설치 패키지를 요구하지 않으며, 구체적인 실행·배포 방식은 별도로 설계합니다.
Module을 정의할 때는 다음 다섯 항목을 명시합니다.
- 업무 목적: 사용자가 달성하려는 일.
- 입력: 업무에 필요한 자료, 설정과 사용자 입력.
- 사용자 흐름: 시작부터 처리·검토·결과 활용까지의 과정.
- 업무 데이터와 규칙: Module이 관리하는 업무 내용·상태와 처리·판정 기준.
- 확인 가능한 결과: 사용자가 확인하거나 활용할 수 있는 응답, 문서, 데이터 또는 완료된 작업.
Module에는 수동 편집, 규칙 기반 처리와 AI 상호작용을 함께 구성할 수 있습니다. 모든 단계가 AI를 사용해야 하는 것은 아닙니다.
업무 데이터는 Module이 관리하는 작업의 대상과 그 내용·상태입니다. 보고서 생성 Module의 ‘9월 실적 보고서’나 문서 정형화 Module에서 검토 중인 문서가 이에 해당합니다.
AI Session은 AI와의 대화와 후속 작업을 이어가기 위한 맥락의 단위입니다. 사용자 관점에서는 AI 대화방으로 이해할 수 있으며, 플랫폼이 연결과 생명주기를 관리합니다.
업무 데이터와 AI Session은 별도로 식별하고 관리하며, 필요에 따라 서로 연결합니다. 보고서 하나를 AI 없이 작성할 수도 있고, 하나의 Session에서 초안부터 수정까지 진행하거나 다른 Session을 열어 검토를 맡길 수도 있습니다. 반드시 일대일로 연결하도록 제한하지 않습니다.
대화 화면을 닫거나 AI 실행이 끝나도 보고서·정형화 문서 같은 업무 데이터는 남아 이어서 사용할 수 있어야 합니다. 선택의 근거와 영향은 ADR-0007에 기록합니다. Session 하나를 여러 업무 데이터나 Module에서 공유할지, 연결을 어떻게 저장·해제할지와 삭제·복구 정책은 후속 설계에서 정합니다.
플랫폼은 업무에 필요한 공통 수단을 제공하고, Module은 그 수단으로 수행할 업무의 의미와 흐름을 결정합니다.
| 영역 | 플랫폼의 책임 | Module의 책임 |
|---|---|---|
| 사용자 경험 | 공통 작업 환경과 Module 접근 기반 | 업무 화면, 입력·편집·검토 흐름 |
| AI 사용 | 에이전트 연결, 세션·실행·취소와 상태 전달 | AI를 사용할 단계, 전달할 업무 맥락, 결과의 업무상 반영 방식 |
| 사용자 승인 | 도구 실행 등의 권한 승인 요청과 응답 처리 | 보고서 수정안 적용, 문서 검토·확정 등 업무 판단 |
| 데이터와 결과물 | 공통 저장·접근 기능과 실행 기록 관리 | 업무 데이터의 의미·구조, 업무 상태·이력과 결과물 생성 규칙 |
업무 데이터의 소유는 그 의미와 규칙에 대한 책임을 뜻합니다. 실제 저장 위치나 데이터베이스를 Module마다 따로 두는 결정은 아닙니다. 플랫폼은 문서의 업무상 확정 조건을 정하지 않으며, Module은 AI를 사용할 때 플랫폼의 공통 연결·실행 기능을 이용합니다.
플랫폼의 AI Agent 관리 기반은 Paseo Server/Client를 사용하도록 결정했습니다. Provider 연결·Agent 생명주기·native 기록은 Paseo에 위임하고, WorkNaru는 업무 API·Module 데이터·사람의 검토·결과물을 소유합니다. 필요한 내부 DaemonClient 사용은 작은 연결 코드에 한정합니다. 기존 대화는 이식하지 않고 새 데이터로 시작하며, 현재 기능·코드의 보존 없이 필요한 부분을 새로 만들 수 있습니다. 실제 필요한 사용자 흐름을 Paseo 기능에 맞게 구성합니다. 현재 실행은 Paseo 기반의 새 Chat을 사용합니다. 플랫폼의 제품 정책·UI·Module은 작은 runtime 인터페이스를 사용하며, Paseo 의존은 연결부와 조립 지점에 한정합니다. 별도 NativeRuntime은 구현하지 않았습니다. 분석 근거는 채택 재검토, 이행 범위와 계획은 Migration 이슈 #35에 기록합니다.
다음은 lg-report-gen과 DocCan 프로젝트가 제공하는 업무를 기준으로 한 예시입니다. 기존 프로젝트의 WorkNaru 통합이나 구현 완료를 뜻하지 않습니다.
| 항목 | 보고서 생성 Module | 문서 정형화 Module |
|---|---|---|
| 업무 목적 | 자료를 바탕으로 보고서를 작성하고 전달 | 원문의 내용과 구조를 검토해 AI가 활용할 참조 자료 생성 |
| 입력 | 작성 목적, 참고 자료, 문서 설정 | 원본 문서, 검토자의 수정·판정 |
| 사용자 흐름 | 자료 준비 → 계획·초안 → 편집·검토 → 내보내기 | 가져오기 → 원문 대조 → 구조·내용 수정 → 확인 → 내보내기 |
| 업무 데이터와 규칙 | 보고서 본문, 작성 설정, 수정 이력, 수정안 적용 규칙 | 문서 구조, 원문 위치, 검토·미해결 상태, 확정본 생성 조건 |
| 결과 | 저장된 보고서와 HTML·PDF | 검토 상태와 원문 근거를 보존한 참조 묶음 |
문서 정형화의 AI 상호작용 단계는 사용자가 제시한 향후 확장 방향입니다. 기존의 대조·수정·검토 흐름에 AI 지원을 더하는 것으로, 현재 구현된 기능으로 간주하지 않습니다.
Chat, 문서 검수와 문서 질의응답도 Module의 예시입니다. 각 Module의 업무와 사용 방식은 달라질 수 있으며, 특정 Module의 요구가 플랫폼 전체나 다른 Module의 구조를 결정하지 않도록 책임을 나눕니다.
Chat은 WorkNaru를 설치하면 처음부터 함께 제공되는 첫 기본 모듈입니다. 이처럼 제품과 함께 제공되는 서비스를 ‘기본 제공 모듈’이라고 부릅니다. 사용자가 나중에 추가하는 서비스는 ‘사용자 추가 모듈’로 구분할 수 있으며, 둘 다 같은 Module 개념과 책임 경계를 따릅니다. 이 구분은 제공 방식에 관한 것이며, 사용자 추가 모듈의 설치 방식은 후속 설계에서 정합니다. 결정 근거
Chat은 대화 목록, 메시지 입력·표시 등 사용자가 AI와 대화하는 경험을 제공합니다. AI 연결, Session 관리, 실행·취소와 도구 사용 권한 승인은 플랫폼이 담당합니다. 다른 Module도 플랫폼의 AI 기능을 직접 이용하며, Chat을 거칠 필요가 없습니다.
가장 단순한 Chat의 대화 흐름으로 공통 AI 실행 환경과 Module 구조를 먼저 검증합니다. 이후 서로 다른 성격의 Module을 추가하며, 기존 기반을 어디까지 공유할 수 있는지와 각 Module이 소유해야 할 책임을 확인합니다.
- 코어는 작고 안정적으로 유지합니다. 실제로 필요한 공통 기반에 집중합니다.
- 업무 능력은 Module이 소유합니다. 업무별 기능과 흐름은 해당 Module 안에서 발전시킵니다.
- 새로운 Module을 독립적으로 추가할 수 있어야 합니다. 기존 Module이나 플랫폼 코어를 크게 수정하지 않고 기능을 확장할 수 있는 구조를 지향합니다.
- 공통화는 실제 요구를 바탕으로 합니다. 미래의 모든 Module을 예측해 거대한 범용 프레임워크를 미리 만들지 않습니다.
- 다양한 Module로 구조를 검증합니다. Chat에서 시작해 성격이 다른 업무 기능을 추가하면서 플랫폼을 점진적으로 확장합니다.
초기에는 이 README에 제품 방향과 책임 경계를, AGENTS.md에 작업 시 지킬 짧고 명확한 규칙을 둡니다. 첫 Chat 흐름을 구현하고 검증하면서 필요한 구조를 정합니다.
- 폴더 구조, 추상화와 공통 계층은 현재 구현에 필요한 만큼만 만듭니다. 아직 없는 기능을 예상해 전체 구조나 상세 설계를 먼저 완성하지 않습니다.
- 기존 결정과 근거는 보존합니다. WebSocket·SQLite 등 기술 선택의 승인 범위는 해당 ADR을 따르며, 확정되지 않은 상세 설계 초안은 실제 구현과 검증에 맞춰 조정할 참고 자료로 사용합니다.
- 폴더·의존성 등 구조 규칙을 강제하는 자동 검사는 같은 위반이 반복되거나 검토 부담이 커졌을 때 도입을 검토합니다. 각 기능에 필요한 설계와 동작 검증은 해당 구현 단계에서 수행합니다.
작업과 의사결정의 기록 및 운영 기준은 프로젝트 기록 규약을 따릅니다.
Module 등록, 화면 연결과 AI 기능 사용의 구체적인 흐름은 Module과 플랫폼의 연결 규칙에서 설명합니다. 후속 상세 설계가 필요한 부분도 함께 명시합니다.
첫 구현의 저장소 구성과 큰 책임 경계는 초기 저장소 구성 설계에서 설명합니다. 세부 폴더·파일 배치는 구현하면서 정합니다.
현재 Chat의 배색·공통 control·권한 패널은 Design System을 따릅니다. 공통 UI 기준은 현재 Chat 동작과 과거에 승인한 전체 화면 시안을 구분합니다. 서비스 탐색과 Module 내부 탐색을 분리하는 설계 원칙은 유지하며, 현재 제공하는 화면과 기능의 범위는 개발 안내를 기준으로 확인합니다.
화면 기술은 제품 방향에 따른 비교를 근거로 React·TypeScript·Vite의 첫 구현을 검증합니다. 선택 제안과 결정 상태는 ADR-0015에 기록합니다.
Daemon은 Paseo가 관리하는 대화·실행·도구 기록을 제품 API로 제공합니다. WorkNaru SQLite에는 대화 연결과 미확정 요청 정보를 저장하며, 정상 완료된 대화는 같은 데이터·Workspace로 재시작한 뒤 이어갈 수 있습니다. Chat의 모델·추론 선택, 추가 권한의 1회 허용·거절과 취소는 UI와 npm run rpc에서 같은 계약으로 처리합니다.
일상적인 실행·종료는 위의 빠른 시작을 따릅니다. 인증 설정과 개별 실행·조회 예시는 로컬 Daemon 개발 안내를 참고하세요.