컴윗 기술 개요
프로젝트를 만들면 관리되는 템플릿 코드, 개발환경, 권한과 실행 인프라가 함께 준비됩니다. 코드 규칙과 데이터베이스 마이그레이션, 보안 기준과 운영 이력까지 같은 프로젝트에 계속 쌓입니다.
프로젝트 생성 원리
01
발급받은 PAT를 개발환경의 환경변수에 보관합니다. 사람과 AI는 같은 사용자 신원으로 컴윗에 연결됩니다.
02
프로젝트 소유권, 참여 범위와 역할을 확인해 접근할 수 있는 코드·협업 정보·인프라의 경계를 만듭니다.
03
큐레이팅된 라이브러리, 사용자·관리자 화면, AI 가이드, 린트와 인프라 연동 스킬이 포함된 코드를 받습니다.
04
관리형 Git 서버부터 스토리지, 데이터베이스, 런타임과 DNS까지 프로젝트 권한 안에서 함께 연결합니다.
05
문서, 칸반, 댓글과 파일을 프로젝트에 연결합니다. 사람과 AI가 같은 기획과 작업 상태를 읽고 갱신합니다.
프로젝트 엔지니어링
관리되는 템플릿 코드에 프로젝트 구조, 최적화된 라이브러리 조합, 인프라 연동 스킬, 권한과 보안 규칙을 함께 넣습니다. 개발자와 AI가 같은 기준으로 수정하고 운영할 수 있도록 계속 엔지니어링합니다.
구성·구현 원리
빈 저장소에서 시작하지 않습니다. Next.js 풀스택 구조, 사용자·관리자 화면, 검증된 의존성, .ai.md와 정적 검사, 인증·데이터베이스·스토리지·SEO·리팩터링 스킬, brrrd와 louhi 연결 기준이 포함된 템플릿 코드로 프로젝트를 생성합니다.
제공·관리 범위
실행 가능한 초기 코드와 개발 명령, 인프라 연결 절차와 검증 기준을 함께 제공합니다. 컴윗은 프레임워크와 라이브러리가 바뀔 때 템플릿·스킬·adapter를 갱신하고 새 프로젝트에 누적된 기준을 적용합니다.
구성·구현 원리
FSD의 관심사 분리 방식에서 착안해 제품 코드를 도메인별 서비스 경계로 나눕니다. 각 서비스 안에서는 화면·상태·API를 분리하고 서버 데이터 접근은 repository로 모아 도메인과 계층 사이의 의존 방향을 명확하게 유지합니다.
제공·관리 범위
도메인별 공개 경계, 사용자·관리자 서비스 분리, 서버·클라이언트 경계와 데이터 흐름을 계층형 .ai.md 가이드와 커스텀 린트로 지속해서 검사합니다. 프로젝트가 커져도 기능의 위치와 변경 영향 범위를 개발자가 예측할 수 있습니다.
구성·구현 원리
프레임워크 기능을 코드에서만 켜지 않고 개발 서버, 인증, 데이터베이스와 brrrd 배포 런타임까지 함께 검증합니다. Next.js가 바뀌면 패키지, adapter, 프로젝트 규칙과 작업 스킬을 같은 호환 단위로 갱신합니다.
제공·관리 범위
App Router, RSC, Server Actions, Route Handlers, Middleware, SSR·동적 렌더링, streaming, cache·revalidation, TypeScript와 CI 검증을 지원합니다. 특정 버전 숫자보다 실제 실행되는 호환 범위를 관리합니다.
구성·구현 원리
풀스택의 각 역할이 겹치지 않도록 검증된 라이브러리를 조합합니다. Better Auth로 인증과 세션, Drizzle로 스키마와 마이그레이션, Tailwind로 스타일링과 디자인 토큰의 기준을 구성합니다.
제공·관리 범위
Tiptap, TanStack Table, React Hook Form, Zod 등 실무에서 자주 쓰는 라이브러리를 미리 선별해 프로젝트에 포함합니다. 컴윗이 라이브러리 간 호환성, 프로젝트 구조에 맞는 기본 설정과 업데이트를 계속 큐레이팅합니다.
구성·구현 원리
공통 지시문 한 파일에 모든 규칙을 몰지 않고 services, api, state, page, app, admin, repository의 7개 핵심 가이드로 나눕니다. AI는 작업 폴더에 가까운 가이드를 읽어 그 계층의 책임과 금지 규칙을 적용합니다.
제공·관리 범위
데이터 접근, Server Action, 상태, UI, routing, 관리자 인증과 서비스 분리 규약을 작업 맥락에 맞게 제공합니다. 사람과 여러 AI 도구가 같은 프로젝트를 수정해도 의존 방향과 작성 순서를 유지합니다.
구성·구현 원리
문서 규칙을 권장사항으로 끝내지 않고 21개의 커스텀 Oxlint 검사로 코드에 적용합니다. API의 DB 직접 접근, app의 Client Component, 잘못된 Server Action, 서비스 경계를 넘는 import 같은 구조 위반을 검증 단계에서 실패시킵니다.
제공·관리 범위
파일 이름, 서버 전용 모듈, 인증 필수 옵션, 이미지·링크 사용, UI 접근성과 layer 구조를 TypeScript 검사와 함께 확인합니다. 생성 코드와 개발자가 고친 코드 모두 같은 validate 절차를 통과합니다.
구성·구현 원리
첫 요청 해석, 인증, DB, 스토리지, SEO와 리팩터링을 6개의 작업 스킬로 관리합니다. 각 스킬에는 지시문뿐 아니라 복사할 코드 자산, 설정 스크립트, 오류 대응과 검증 순서가 포함됩니다.
제공·관리 범위
AI가 매번 다른 방식으로 환경을 구성하지 않고 검증된 절차를 재사용합니다. 프레임워크와 라이브러리가 바뀌면 스킬과 템플릿을 같이 고쳐 이후 프로젝트에도 같은 개선을 적용합니다.
구성·구현 원리
데이터 접근은 repository로 모으고 스키마를 TypeScript 코드로 관리합니다. 변경은 Drizzle Kit의 generate·migrate 절차로만 만들고 마이그레이션 파일과 적용 순서를 Git 이력에 함께 남깁니다.
제공·관리 범위
스키마 정의, 재현 가능한 마이그레이션 이력, Turso·louhi 연결 설정과 배포 환경별 데이터베이스 구성을 지원합니다. 사람이나 AI가 운영 데이터베이스를 임의로 고치지 않고 같은 변경 절차를 따르게 합니다.
구성·구현 원리
사용자·관리자 인증, 관리자 페이지의 접근 경계, 프로젝트 참여 범위와 역할, Server Action 인증, 서버 전용 설정과 외부 리소스 소유권 검사를 코드 구조와 정적 검사에 넣습니다.
제공·관리 범위
Better Auth 기반 인증, 사용자·관리자 화면 분리, 비관리자 접근 차단, 프로젝트별 읽기·쓰기와 소유자 권한, 환경값 비노출과 인증 누락 검사를 제공합니다. 보안 기준을 생성 코드와 검증 절차에 적용합니다.
구성·구현 원리
프로젝트별 design.md에 색상, 타이포그래피, 간격, 컴포넌트 형태, 반응형과 상호작용 원칙을 기록합니다. AI는 화면 작업 전에 이 기준을 읽고, @comwit/ui의 접근성 기반과 프로젝트가 소유하는 컴포넌트 코드를 제품에 맞게 확장합니다.
제공·관리 범위
현재 프로젝트 템플릿에 35개의 기본 UI 구성요소와 디자인 토큰 사용 규칙을 제공합니다. shadcn처럼 코드를 직접 고칠 수 있어 제품마다 자체 디자인 시스템을 구축하면서도 프로젝트 전체의 시각·상호작용 기준을 유지할 수 있습니다.
구성·구현 원리
Zustand의 단순한 store 인터페이스와 TanStack Query의 서버 상태 모델에서 착안해 state, query와 action을 한 계층으로 묶었습니다. 요청마다 store를 만들고 서버 초기 상태를 provider로 전달하는 패턴을 사용합니다.
제공·관리 범위
Next.js와 SSR에서 요청 간 상태가 섞이지 않는 초기화, 클라이언트 query·mutation, Server Action 연결과 상태 선택 API를 제공합니다. 페이지가 데이터 호출 방식을 직접 소유하지 않게 합니다.
구성·구현 원리
Ssgoi를 활용해 Next.js의 실제 라우트 경계에 화면 진입과 이탈 전환을 연결합니다. 모바일 웹앱의 최상위·상세 화면 구조와 앞·뒤 페이지 관계도 작업 스킬로 설정합니다.
제공·관리 범위
웹 서비스에 앱과 같은 페이지 전환과 애니메이션을 제공합니다. 기존 라우팅을 유지하면서 화면별 전환을 제품에 맞게 설정할 수 있으며 Ssgoi 기술 문서로 연결됩니다.
인프라
컴윗은 Clovair 운영사의 호스팅 서비스를 이용해 런타임과 데이터베이스를 제공합니다. 여기에 Git, 스토리지, 배포와 도메인을 연결하고 콘솔, CLI, API와 MCP에서 같은 프로젝트 권한으로 관리합니다.
구성·구현 원리
프로젝트별 관리형 저장소와 사용자별 Git PAT를 연결합니다. 개발 세션은 필요할 때 가동해 main 기준 코드, 의존성과 개발 서버를 준비하고, 개인 credential로 원격과 로컬 작업의 인증을 분리합니다.
제공·관리 범위
저장소·commit 이력, 프로젝트 역할 기반 접근, 전용 HTTPS 개발 주소, 유휴 세션 resume와 장애 시 작업공간 복구를 제공합니다. 배포는 같은 저장소에 push된 코드를 기준으로 시작합니다.
구성·구현 원리
컴윗은 Clovair 운영사가 제공하는 brrrd 호스팅 서비스를 이용합니다. Next.js 프로젝트는 next.config의 @brrrd/adapter를 통해 런타임 앱이 실행할 서버 번들로 준비되고, 요청이 오면 서울 리전의 V8 isolate에서 코드를 실행합니다.
제공·관리 범위
컨테이너·서버 관리 없는 요청 단위 실행, 밀리초 단위 콜드 스타트, 런타임 앱 ID와 활성 빌드를 제공합니다. 코드와 데이터는 표준 Next.js·libSQL 기반으로 유지해 다른 인프라로 이전할 수 있습니다.
구성·구현 원리
CLI가 빌드 패키지를 런타임 앱에 배포하면 빌드 ID를 만들고 활성 빌드를 전환합니다. 빌드 이력과 배포 시각을 보존해 이전 빌드를 다시 활성화하는 롤백을 제공합니다.
제공·관리 범위
CLI 기반 배포, 배포·빌드 목록, 활성 상태, 빌드·실패 로그, 서비스 URL과 롤백을 지원합니다. 컴윗 웹과 MCP에서는 Git 커밋·푸시 뒤 배포 생성과 상태 확인을 같은 프로젝트에서 수행합니다.
구성·구현 원리
런타임 앱의 환경 값은 서버 측 Platform API에 저장하고 키 목록만 화면과 도구에 반환합니다. 값은 입력 뒤 브라우저나 MCP 응답에 다시 포함하지 않으며, 전용 비밀 저장소와는 구분되는 런타임 환경변수로 관리합니다.
제공·관리 범위
환경변수 추가·갱신·삭제와 DB URL·토큰, 외부 서비스 설정값 주입을 제공합니다. 프로젝트 MCP에서도 목록 조회·추가·수정·삭제가 가능하고 기존 값은 도구 응답에 재노출하지 않습니다.
구성·구현 원리
런타임 앱을 프로젝트가 관리하는 도메인의 최상위 주소나 하위 도메인에 자동 연결하고, 외부 DNS 호스트 이름은 수동으로 연결합니다. 런타임 관측 모델은 데이터베이스 사용량과 분리해 요청, 오류, 지연시간과 콜드 스타트 기준으로 관리합니다.
제공·관리 범위
자동 DNS 호스트 이름, 외부 호스트 이름, 연결 상태와 관리형 DNS 레코드를 제공합니다. 런타임 관측은 요청 수, 오류, p50·p95·p99 지연시간과 콜드 스타트를 표준 관측 항목으로 정의합니다.
구성·구현 원리
컴윗은 Clovair 운영사가 제공하는 Turso 기반 louhi 데이터베이스 호스팅을 이용합니다. 프로젝트별 diskless libSQL tenant URL과 토큰을 발급하고 서울 리전에서 @tursodatabase/serverless 또는 Drizzle turso dialect로 연결합니다.
제공·관리 범위
인스턴스 용량을 먼저 산정하지 않는 데이터베이스 생성, 표준 URL, 최초 한 번만 표시되는 토큰, serverless 연결 안내와 Drizzle generate·migrate 흐름을 제공합니다.
구성·구현 원리
Cloud 콘솔이 tenant URL을 통해 테이블·뷰를 탐색하고 SQL을 실행합니다. 쿼리 기록을 시간, 구문 종류와 성공 여부로 분류해 데이터베이스 실행 기록을 분석합니다.
제공·관리 범위
테이블 탐색기, SQL 편집기, execute·prepared get·all·batch, 쿼리 검색과 분석을 제공합니다. 개발자와 AI가 별도 DB 도구 없이 schema와 데이터를 조회하고 디버깅할 수 있습니다.
구성·구현 원리
데이터베이스 사용량을 시간 단위로 집계하고 런타임 지표와 분리합니다. 표준 tenant ID를 기준으로 요청량, 쿼리 비용과 WAL 변화를 읽습니다.
제공·관리 범위
24시간·7일 SQL 요청·구문·오류, 읽고 쓴 행 수, 평균 쿼리 시간, 요청·응답 용량, WAL 프레임·용량과 시간대별 추이를 제공합니다.
구성·구현 원리
PITR은 기존 DB를 덮어쓰지 않고 선택한 시각이나 복구 지점에서 새 데이터베이스를 생성합니다. 복구 DB로 애플리케이션을 다시 연결하는 단계는 명시적으로 분리해 원본을 보존합니다.
제공·관리 범위
복구 가능 기간과 복구 지점, 비파괴 복원, 데이터베이스 일시 중지·재개, tenant 토큰 교체와 소프트 삭제를 제공합니다. 복구·수명주기 작업은 서버 전용 관리 API를 거칩니다.
구성·구현 원리
S3 호환 오브젝트 스토리지를 사용하고 서버가 presigned PUT URL을 발급해 브라우저가 파일을 직접 업로드합니다. 업로드 경로는 프로필, 문서, 작업, 쇼케이스와 프로젝트 첨부처럼 용도별로 분리합니다.
제공·관리 범위
이미지·일반 파일 업로드, 공개 파일 URL, 클라이언트 이미지 크기 조정과 변환본을 제공합니다. 큰 파일을 애플리케이션 서버가 다시 전달하지 않아도 됩니다.
구성·구현 원리
정기 작업은 프로젝트에 실행 주기, endpoint와 webhook secret을 저장하고 실행마다 상태와 로그를 남깁니다. secret 생성과 호출 방법도 MCP 안내로 제공해 AI가 올바른 인증 흐름으로 구성합니다.
제공·관리 범위
컴윗 웹과 MCP에서 정기 작업 목록, 생성·수정·삭제, webhook secret 생성, 실행 이력·로그 조회와 연동 안내를 제공합니다. AI가 배포 후 정기 작업까지 같은 프로젝트에서 설정할 수 있습니다.
구성·구현 원리
최상위 도메인을 프로젝트에 추가하면 관리형 네임서버를 발급하고 등록기관 위임을 검사합니다. 위임이 확인된 뒤 Route 53 관리 영역에서 레코드를 관리하고 런타임 호스트 이름과 인증서 검증 레코드를 연결합니다.
제공·관리 범위
도메인 소유·위임 상태, A·AAAA·CNAME·TXT·MX 레코드와 TTL, 동기화 상태, 자동·사용자 지정 호스트 이름과 SSL 발급·갱신을 지원합니다. 기존 MX·SPF·DKIM·DMARC 레코드도 이전할 수 있습니다.
구성·구현 원리
Cloud 콘솔과 comwit CLI는 api.cloud.comwit.io의 공개 Platform API를 사용합니다. CLI는 기기 인증 또는 한 번만 표시되는 개인 cwt_ 토큰으로 로그인하고 프로젝트 권한 안에서 명령을 실행합니다.
제공·관리 범위
CLI의 프로젝트, 데이터베이스, 런타임 앱, 배포와 도메인 명령, API 토큰 생성·사용 기록·폐기를 제공합니다. CI에는 개인과 분리된 프로젝트 토큰과 app:deploy·app:read 권한 범위를 사용할 수 있습니다.
구성·구현 원리
사용자별 PAT로 호출자를 식별하고 프로젝트 참여 범위, 역할과 대상 자원의 소유 프로젝트를 매 요청마다 확인합니다. AI도 연결된 사용자와 동일한 권한 검사를 통과하며 다른 프로젝트의 자원에는 접근할 수 없습니다.
제공·관리 범위
읽기·쓰기와 소유자 전용 작업을 구분하고, 사용자가 소유하거나 참여 권한을 받은 프로젝트 안에서만 문서·칸반·파일, 환경변수, 정기 작업, 배포, 런타임, 데이터베이스와 도메인을 조회·관리할 수 있습니다.
구성·구현 원리
컴윗 DB, Git, 개발 세션과 Cloud 자원별 기준 데이터를 구분하고 외부 생성 실패에는 보상 정리를 적용합니다. 반복 요청은 멱등하게 처리하고 누락·불일치는 재조정 절차로 다시 맞춥니다.
제공·관리 범위
중복 생성 방지, 실패한 외부 자원 정리, 참여 권한·저장소·세션 재동기화, 프로젝트 소프트 삭제와 감사 이력 기반 복구 경계를 제공합니다.
Git 이력, 코드 규칙, 라이브러리와 디자인 시스템, 스키마·마이그레이션, 배포와 운영 상태가 함께 남아 개발자가 그대로 이어서 유지보수할 수 있습니다.
