Basalt는 짧은 프론트엔드 수정 요청을 AI가 계획하고, 실행을 보조하고, 검증 결과와 후속 정리까지 남기는 작업 관리 프로토타입입니다.
프론트엔드 개발자는 작은 UI 수정 요청 하나를 처리할 때도 요청 해석, 작업 순서 정리, 수정 범위 확인, 결과 검토, 인수인계 정리를 반복합니다. Basalt는 이 반복 비용을 줄이기 위해 요청 등록 -> 계획 -> 실행 -> 검증 -> 정리 흐름을 하나의 도구 안에 묶었습니다.
Basalt는 작은 UI 수정 요청이 자주 들어오는 프론트엔드 개발자와 팀을 주요 사용자로 둡니다. 사용자는 프로젝트를 연결하고 태스크를 만든 뒤, AI가 만든 작업 계획, 실행 로그, 코드 변경 결과, 검증 결과, 후속 정리 내용을 한 화면 흐름에서 확인할 수 있습니다.
짧은 UI 수정 요청도 실제 작업에서는 다음 단계를 동반합니다.
- 모호한 요청을 실제 작업 단위로 해석
- 어떤 순서로 수정할지 계획
- 수정 후 영향 범위와 이상 여부 확인
- 작업 내용을 로그, 리뷰, 인수인계 형태로 정리
각 단계는 작아 보이지만 반복되면 누적 비용이 큽니다. Basalt가 해결하려는 문제는 프론트엔드 개발자의 반복적인 요청 해석, 실행 조율, 검토 정리 업무를 줄이는 것입니다.
Basalt의 기본 사용 흐름은 다음과 같습니다.
- 로컬 프로젝트를 연결합니다.
- 처리할 태스크를 생성합니다.
- AI가 태스크를 바탕으로 작업 계획을 만듭니다.
- 실행 단계에서 코드 수정과 step별 로그 기록이 이어집니다.
- 검증 결과, 작업 이력, 복구 가이드, 인수인계 요약을 확인합니다.
핵심은 코드 결과만 보여주는 것이 아니라, 요청이 처리되는 과정을 태스크 상태, 실행 로그, 검증 결과, 후속 정리 정보로 남기는 것입니다.
Basalt에서 AI는 부가 기능이 아니라 핵심 실행 주체입니다. AI가 없다면 Basalt는 단순 칸반 보드에 가깝습니다.
| 단계 | AI 역할 | 결과 |
|---|---|---|
| 계획 | 요청을 분석하고 workflow를 생성 | 실행 가능한 step 목록 |
| 실행 | 프로젝트 문맥을 읽고 코드 수정 보조 | 변경 파일과 실행 로그 |
| 검토 | 결과와 로그를 바탕으로 위험과 개선점 확인 | 리뷰/검증 메타데이터 |
| 정리 | 실패 원인, 복구 방향, 인수인계 문서 생성 | 한국어 Markdown 요약 |
역할별 모델 구성은 아래와 같습니다. 실제 기본값과 운영 규칙은 docs/llm.md에 정리되어 있습니다.
FAST_MODEL: 빠른 판단, 경량 의사결정, 일부 스킬 인자 생성SMART_MODEL: 분석, workflow 설계, 검토, 검증, 구조화 응답 생성CODING_MODEL: 코드 생성, 수정, repair 작업
Basalt는 analyze_task -> create_workflow -> consult_agents 흐름으로 필요한 agent와 skill을 고르고, ProjectProfiler가 프로젝트 구조, 설치 패키지, 라우터 정보, stack rules를 프롬프트에 주입합니다. 실행 결과는 Supabase의 태스크 메타데이터와 실행 로그에 저장됩니다.
Basalt는 태스크를 다음 순서로 처리합니다.
ProjectProfiler가 대상 프로젝트의 파일 구조, package.json, 라우터, UI 컴포넌트, 설치 패키지를 읽습니다.- AI가 사용자 요청과 프로젝트 문맥을 바탕으로 작업 계획과 workflow step을 만듭니다.
- Orchestrator가 step별 agent와 skill을 선택하고, 코드 읽기·쓰기·검토·검증 작업을 순서대로 실행합니다.
- 코드 생성 단계에서는 라우터 규칙, 설치된 패키지, import 가능 경로, RSC/metadata 제약을 함께 넣어 잘못된 출력을 줄입니다.
- 실행 후에는 QA smoke, verify, screenshot/responsive 확인 결과를 저장하고, 실패 신호가 있으면 repair 또는 복구 가이드로 연결합니다.
프롬프트에는 사용자 요청, 명확화 답변, 스펙 확장 내용, 프로젝트 구조, 설치된 패키지, 라우터 규칙, 이전 실행 로그, 검증 결과가 함께 들어갑니다. 그래서 AI는 일반적인 코드 답변이 아니라 연결된 프로젝트의 실제 문맥 안에서 계획과 수정 방향을 생성합니다.
기존 AI 코딩 도구가 “코드를 생성한다”에 초점을 둔다면, Basalt는 “짧은 수정 요청을 끝까지 처리하는 과정”을 제품 단위로 봅니다.
- 태스크 상태를 따라 계획, 실행, 검증, 정리까지 연결합니다.
- 역할별 agent와 skill 조합으로 실행 단계를 나눕니다.
- 결과 코드뿐 아니라 실행 로그, 검증 결과, 작업 이력을 함께 남깁니다.
- 실패와 검증 결과를 다음 수정, 복구 가이드, 인수인계 요약에 연결합니다.
- 로컬 프로젝트 연결
- 태스크 생성 및 칸반 상태 관리
- AI 기반 계획 생성
- 실행 단계에서 코드 변경과 step별 실행 로그 기록
Test단계에서 검증 결과, 작업 이력, verification 상태 저장agent-browser기반 QA 캡처와검수 완료탭의 결과 확인- 복구 가이드, 인수인계 요약 같은 후속 정리 정보 생성
동작 여부는 다음 결과로 확인할 수 있습니다.
Tasks.workflow: AI가 생성한 작업 계획Execution_Logs: step별 agent/skill 실행 로그metadata.fileChanges: 코드 변경 파일과 변경 이력metadata.qaPageCheck: 대상 앱 페이지 스모크 결과metadata.qaSignoff: 검수 완료 탭에 표시되는 최종 검증 문구와 캡처 정보.basalt/basalt-qa/<taskId>/: 대상 프로젝트에 저장되는 QA 캡처 PNG- 복구 가이드와 인수인계 Markdown: 실패 후 다음 시도 또는 팀 공유에 쓰는 정리 결과
Basalt는 아래 순서로 사용할 수 있습니다.
- 칸반 보드의
Request컬럼에서 프로젝트를 선택하고 짧은 태스크를 생성합니다. Plan단계로 이동해 작업 계획을 만듭니다.Dev (Working)단계에서Execute를 실행합니다.Test단계와 태스크 상세 화면에서 실행 로그와 검증 결과를 확인합니다.Task Details에서 복구 가이드, 인수인계 요약,검수 완료탭의 QA 결과를 확인합니다.
화면에서는 다음 결과를 확인할 수 있습니다.
- 태스크가
Request -> Plan -> Dev (Working) -> Test로 이동하는 흐름 Task Details와LogViewer에 남는 실행 로그Test단계와검수 완료탭의 검증 결과, 작업 이력, QA 캡처- 복구 가이드와 인수인계 요약 생성 결과
Basalt는 다음 구조로 동작합니다.
- Next.js App Router: 칸반 UI와 API 라우트를 한 프로젝트 안에서 구성
- Supabase: 프로젝트, 태스크, 실행 로그, 메타데이터 저장
- Ollama 호환 LLM 호출: 계획, 분석, 코드 생성, 검토를 역할별 모델로 분리
- Orchestrator + Agent + Skill 레이어: 태스크를 step 단위로 실행하고 검증/수리 루프 제어
사용자 액션 기준 흐름은 UI -> API Route -> Orchestrator -> Agent/Skill -> LLM 또는 파일 작업 -> Supabase 로그/메타데이터 -> UI 갱신입니다. 자세한 구조는 docs/architecture/overview.md를 참고하세요.
node -v # 권장: >= 20.9.0
npm install
cp .env.example .env.local
npm run dev브라우저에서 http://localhost:3000을 엽니다.
실행 전 준비가 필요합니다.
- Supabase 프로젝트 생성 후
.env.local에 URL과 anon key 설정 - supabase/schema.sql을 Supabase SQL Editor에서 실행
- Ollama 또는 호환 가능한 모델 엔드포인트 준비
- 연결해서 테스트할 로컬 프론트엔드 프로젝트 준비
자세한 설치와 운영 옵션은 docs/setup.md를 참고하세요.
| 문서 | 내용 |
|---|---|
| docs/README.md | 전체 문서 인덱스 |
| docs/features.md | 핵심 기능, 화면 흐름, 확장 기능 |
| docs/api.md | API 엔드포인트와 용도 |
| docs/llm.md | 사용 모델, 프롬프트, LLM 처리 구조 |
| docs/setup.md | 설치, 실행, 환경 변수, 운영 가이드 |
| docs/architecture/overview.md | 시스템 전체 구조 |
| supabase/schema.sql | 최소 실행에 필요한 Supabase 테이블 스키마 |