Night Worker

Claude Code는 원래 대화형 CLI다. 이걸 비대화형으로 제어하려면 child_process.spawn으로 호출하면서 --output-format stream-json 플래그를 붙이면 된다. 그러면 구조화된 NDJSON 스트림이 stdout으로 나온다.

실행 모드는 세 가지 플래그로 스위칭된다 — --permission-mode auto와 --allowedTools를 작업 설정에 따라 조합한다. 모델(sonnet/opus/haiku), 비용 한도, MCP 설정도 모두 커맨드라인 인자로 전달한다. 코드 변경이 포함된 작업은 체크박스 하나로 git worktree 격리 실행을 켤 수 있어, 메인 브랜치를 건드리지 않고 밤 사이 실험할 수 있다.

CLI 실행을 프로세스로 감싸면서 권한 범위, 비용 한도, 작업 격리와 중단 조건을 애플리케이션 상태로 관리했다.

Claude Code의 stream-json 출력은 라인 단위 NDJSON이다. 스트림이 들어오는 즉시 라인별로 파싱해서 role을 기준으로 구조화한다. assistant, tool_use, tool_result, system — 각각 다른 형태로 저장된다.

기록은 두 곳에 동시에 한다. SQLite에는 쿼리 가능한 구조화 데이터로, JSONL 파일에는 원본 아카이브로. SQLite는 대시보드 검색과 필터링을 위한 것이고, JSONL은 나중에 재처리하거나 외부로 내보낼 수 있도록 남겨두는 것이다.

프론트엔드 로그 뷰어는 SSE로 연결된다. 실행 중에는 상태 메시지, 도구 호출과 결과를 확인할 수 있고, 종료 후에는 같은 기록을 검색하거나 다시 처리할 수 있다.

--mcp-config로 MCP 서버 설정을 넘기면 Claude Code가 외부 도구를 쓸 수 있다. Night Worker에서는 글로벌 MCP 설정을 정의해두고, allowedTools 패턴 매칭으로 태스크마다 사용 가능한 도구를 제한한다.

Atlassian 연동에서는 코드 리뷰 결과를 바탕으로 설정된 프로젝트에 Jira 이슈를 등록하는 작업을 구성했다. 외부 시스템을 변경하는 도구는 태스크별 허용 목록에 포함된 경우에만 사용할 수 있다.

이 구조로 저장소 안의 작업과 팀 도구의 후속 작업을 한 실행 기록에서 추적할 수 있다.

초기 버전에는 review/implement/analyze 같은 태스크 타입을 코드에 박아두고 타입별 시스템 프롬프트를 주입했다. 그런데 실제로 팀이 쓰는 작업은 훨씬 다양했다 — 타입을 늘릴수록 경계가 애매해졌고, 정작 자주 쓰는 패턴은 프롬프트 안에 숨어 있었다.

그래서 타입을 걷어내고 프리셋으로 옮겼다. 자주 쓰는 지시문을 설정에서 관리하고, 작업 등록 시 드롭다운으로 불러와 채운 뒤 필요하면 그 자리에서 수정한다. "비대화형 실행이니 질문하지 말고 스스로 판단하라"는 기본 지시를 공통으로 넣고, 나머지는 팀이 프리셋으로 누적한다.

코드가 단순해졌고, 무엇보다 팀의 실제 사용 패턴이 프리셋 목록에 드러나기 시작했다. "이런 프롬프트가 잘 먹힌다"는 암묵지가 설정 화면에 축적되는 건 예상하지 못한 효과였다.

SaaS로 만들 수도 있었지만 설치형을 선택했다. 이유는 단순하다 — 팀이 이미 Claude Code를 쓰고 있고, API 키 관리나 별도 권한 설정 없이 그걸 그대로 활용하고 싶었다. 중앙 서버를 두면 보안 이슈도 생기고, 팀마다 Claude 플랜이 다르면 복잡해진다.

배포는 pm2 start 하나로 끝난다. Storage는 SQLite를 쓰기 때문에 DB 서버가 필요 없다. WAL 모드를 켜서 스케줄러가 쓰는 동안 대시보드가 읽을 수 있게 했다.

동시성 제어도 필요했다. 여러 태스크가 같은 프로젝트에서 동시에 실행되면 충돌이 생긴다. 프로젝트 단위 lock과 글로벌 concurrency 제한을 함께 두어 안전하게 처리한다.