Qwen Code 슬래시 명령어를 사용하여 Achu 앱을 구축하는 방법

이 블로그 포스트에서는 토큰을 낭비하거나 세션 중간에 문맥(Context)을 잃지 않고, Qwen Code의 슬래시 명령어(slash commands)와 워크플로우 전략을 사용하여 저의 스크린샷 미화 앱인 Achu를 구축하는 방법을 살펴보겠습니다.

Achu를 들어본 적이 없다면, 이는 Electron + React + TypeScript로 구축된 데스크톱 앱입니다. 이 앱은 스크린샷 미화(screenshot beautification), Privacy Guard (오프라인 OCR 레드액션), Auto-Vibe (팔레트 추출 배경), 그리고 GitHub 연동 기능이 있는 AI 버그 에이전트(AI Bug Agent) 기능을 제공합니다. 이는 제가 진심으로 자랑스럽게 생각하는 사이드 프로젝트이며, Qwen Code는 이를 위한 저의 주력 에이전트 방식 코딩 CLI(agentic coding CLI)가 되었습니다.

한 개발자가 Electron, React, TypeScript로 구축된 데스크톱 스크린샷 미화 앱인 Achu를 구축하기 위해 오픈 소스 에이전트 방식 코딩 CLI인 Qwen Code를 사용하는 일상적인 워크플로우를 공유합니다. 이 포스트는 /init, /plan, /compress, /remember, /btw와 같은 슬래시 명령어를 사용하여 문맥(context)을 관리하고, 토큰 비용을 줄이며, 세션 전반에 걸쳐 일관된 출력을 유지하는 방법을 다룹니다.

핵심 접근 방식은 코드를 작성하기 전에 반복적인 /plan 세션을 통한 명세 기반 계획(spec-driven planning)을 중심으로 하며, 독립적인 작업을 위한 병렬 서브 에이전트(parallel subagents)와 /compress 및 /clear를 사용한 엄격한 문맥 위생(context hygiene)을 결합합니다. 추가적인 관행으로는 모델에게 문서 대신 라이브러리 소스 코드를 가리키게 하는 것과, 세션 전반에 걸쳐 아키텍처 결정 사항을 유지하기 위해 /remember를 사용하는 것이 포함됩니다.

이것은 Qwen Code가 무엇인지에 대한 튜토리얼이 아닙니다. 제가 실제로 매일 어떻게 사용하는지, 제가 의존하는 슬래시 명령어 기술, 그리고 터미널에서 LLM으로 실제 작업을 완수하기 위해 필요한 규율에 관한 것입니다.

모든 것은 Google Antigravity로 시작되었지만, 5시간의 리셋과 주간 제한이 저의 생산성과 사고 흐름을 저해하고 있습니다. 그래서 저는 더 저렴하고 오픈 소스인 모델로 전환해야 했고, Qwen을 선택했습니다.

왜 Qwen Code인가?

저는 Claude Code, Gemini CLI, 그리고 그 외 수많은 도구들을 사용해 보았습니다. Qwen Code는 오픈 소스(open source)이며, 뛰어난 서브 에이전트(subagent) 지원과 풍부한 슬래시 명령어(slash command) 시스템을 갖추고 있습니다. 또한 Qwen Max는 복잡한 TypeScript 및 Electron 내부 구조를 추론하는 데 진정으로 강력한 성능을 보여줍니다.

제가 주로 사용하는 모델은 Qwen Max입니다. /recap이나 프롬프트 제안과 같은 가벼운 작업을 수행할 때는 비용을 절감하기 위해 /model --fast qwen3-coder-flash 명령어로 빠른 모델을 설정합니다.

/init 및 프로젝트 컨텍스트(Project Context) 설정

새로운 프로젝트를 시작하거나 며칠 만에 Achu로 돌아왔을 때 제가 가장 먼저 하는 일은 다음과 같습니다:

/init

이 명령어는 현재 디렉토리를 분석하여 초기 컨텍스트(context) 파일을 생성하며, 본질적으로 Qwen Code에게 프로젝트의 지도를 제공합니다. 제가 단 한 마디를 내뱉기도 전에 폴더 구조, 주요 파일들을 파악하고 기초적인 이해도를 구축합니다.

/init 이후에는 프로젝트에 대한 몇 단락의 설명을 수동으로 추가합니다. 저는 이것을 새로운 개발자를 위한 팀 온보딩(onboarding) 문서를 작성하는 것처럼 취급합니다. Qwen에게 Achu가 무엇인지, 현재 마일스톤(milestone)은 무엇인지, 어떤 기술 스택(tech stack)을 사용하는지, 그리고 알려진 제약 사항(예: Electron IPC 경계, Upstash Redis 통합, 또는 Gumroad 기반의 수익화 모델 등)은 무엇인지 알려줍니다.

이러한 사전 투자는 나중에 발생할 엄청난 양의 반복적인 대화를 줄여줍니다.

/plan을 이용한 명세 기반 계획(Spec-Driven Planning)

새로운 기능을 구축하고 싶을 때, 저는 단순히 모호한 요청을 던지고 결과가 좋기를 바라지 않습니다. 대신 /plan을 사용하여 Qwen Code를 계획 모드(planning mode)로 전환합니다.

/plan Implement the Privacy Guard redaction pipeline

계획 모드에서 Qwen은 분석하고 사고하지만, 어떤 파일도 건드리지 않습니다. 이것이 핵심입니다. 이는 에이전트(agentic) 관점에서 "행동하기 전에 생각하라"는 원칙과 같습니다.

제가 실제로 하는 일은 사양(spec)을 반복 개선하기 위해 계획 모드(plan mode)에서 여러 차례의 턴(turn)을 실행하는 것입니다. 저는 "사양(spec)"을 인터페이스 계약(interface contracts), 데이터 흐름(data flow), 오류 경로(error paths), 수락 기준(acceptance criteria) 등 구축되어야 할 내용을 설명하는 공식적인 산출물(artifact)로 생각합니다. 이것은 막연한 아이디어가 아닙니다. 개발자(또는 하위 에이전트(subagent))가 구현할 수 있을 만큼 충분히 정밀한 것입니다.

루프는 다음과 같습니다:

/plan 명령어로 계획 모드(planning mode) 진입
기능에 대해 상세히 설명 — 무엇을 하는지, 무엇을 하지 않는지, 예외 케이스(edge cases)
Qwen에게 접근 방식(approach)을 제안하도록 요청
아키텍처(architecture)에 맞지 않는 부분은 반박(push back)
수정된 계획(revised plan) 요청
사양(spec)이 견고해질 때까지 2~3회 반복

구현의 품질은 거의 전적으로 사양(spec)의 품질에 의해 결정됩니다. 코드 한 줄을 쓰기 전에 수행하는 이 다중 턴(multi-turn) 정제 과정은 제가 에이전트 기반 코딩 도구(agentic coding tool)를 사용하며 기른 가장 가치 있는 습관입니다.

기본적으로 Qwen은 후속 질문을 던질 것입니다. 하지만 모델에게 질문을 하라고 명시적으로 말하는 것을 항상 권장합니다.

비동기 작업을 위한 하위 에이전트 (Subagents for Async Work)

사양(spec)이 확정되면, 독립적으로 수행할 수 있는 모든 작업에 하위 에이전트(subagents)를 공격적으로 사용합니다.

Qwen Code의 하위 에이전트(subagent) 시스템을 사용하면 .qwen/agents/ 디렉토리에 Markdown 파일로 특화된 에이전트를 정의할 수 있습니다. 각 에이전트는 고유한 시스템 프롬프트(system prompt), 도구 허용 목록(tool allowlist), 그리고 모델을 가집니다. 이를 명시적으로 호출하거나 Qwen이 자동으로 위임하도록 할 수 있습니다.

Achu를 위해 저는 몇 가지 맞춤형 하위 에이전트(custom subagents)를 가지고 있습니다:

Vitest 및 Electron 테스트 패턴에 집중하는 테스트 하위 에이전트 (testing subagent) (이에 대해서는 아래에서 더 자세히 다룹니다)
plan 모드에서 실행되며 파일 읽기만 수행하는 코드 리뷰어 하위 에이전트 (code reviewer subagent)

여기서 핵심적인 능력은 **서브 에이전트 분기 (Fork Subagents)**입니다. Qwen이 여러 작업을 병렬로 실행해야 할 때, 암시적으로 분기(fork)를 수행할 수 있습니다. 분기된 에이전트는 부모의 컨텍스트(context)를 상속받고, 백그라운드에서 실행되며, 프롬프트 캐시 접두사(prompt cache prefix)를 공유합니다. 즉, 제가 Qwen에게 "Privacy Guard를 위한 IPC 핸들러, Ollama 통합, 그리고 Upstash Redis 투표 흐름을 동시에 조사해줘"라고 요청하면, 토큰 비용을 세 배로 늘리지 않고도 세 개의 병렬 에이전트를 분기할 수 있다는 의미입니다.

저는 작업을 다음과 같이 명시적으로 표현합니다:

"서브 에이전트를 사용하여 이 세 가지 조사를 병렬로 수행하고 보고해줘."

이렇게 하면 메인 대화의 집중도를 유지하면서 단순 반복 작업(grunt work)을 동시에 처리할 수 있습니다.

프로젝트 레벨의 서브 에이전트 설정은 .qwen/agents/testing.md에 위치하며 다음과 같은 형태를 가집니다:

---
name: testing
description: "Achu를 위한 Vitest 단위 테스트 및 Electron 통합 테스트를 작성합니다. 테스트 관련 작업에는 PROACTIVELY(적극적으로) 사용하세요."
...

설명에 포함된 "Use PROACTIVELY(적극적으로 사용하세요)"라는 문구는 중요합니다. 이는 메인 모델이 명시적인 요청 없이도 테스트 작업을 이곳으로 위임하도록 신호를 보냅니다.

컨텍스트 위생 (Context Hygiene): /summary, /compress, 그리고 /clear

이 부분은 긴 에이전트 세션(agentic sessions)을 다룰 때 대부분의 사람들이 실패하는 지점입니다. 사람들은 모델이 환각(hallucination)을 일으키거나, 이전 지침을 잊어버리거나, 일관성 없는 출력을 생성하기 시작할 때까지 컨텍스트가 무제한으로 커지도록 방치합니다. 저는 컨텍스트를 자원이 제한된 기기의 메모리처럼 다루는 법을 배웠습니다.

저의 위생 규칙은 다음과 같습니다:

주요 작업 단위가 완료된 후:

/summary

이 명령은 대화 기록으로부터 프로젝트 요약을 생성합니다. 저는 이 요약을 외부에 저장해 두었다가 세션을 재시작할 때 참조합니다.

컨텍스트 창(context window)이 가득 차고 있을 때:

/compress

이 명령은 채팅 기록을 압축된 요약본으로 대체하여, 논의된 내용의 의미론적 본질(semantic essence)은 보존하면서 토큰을 확보합니다. 이를 손실이 있지만 실용적인 체크포인트(checkpoint)라고 생각하면 됩니다.

Qwen이 주제에서 벗어나기 시작할 때:

모델이 프로젝트 제약 조건(constraints)에 맞지 않는 답변을 하거나, 이미 배제한 패턴을 제안하거나, 혹은 단순히 맥락을 놓치며 주제에서 벗어나기 시작한다면, 저는 논쟁하지 않습니다. 만약 이런 일이 두 번 연속으로 발생하면, 저는 다음과 같이 입력합니다:

/clear

그다음 /init과 새로운 설명을 사용하여 처음부터 컨텍스트(context)를 다시 불러옵니다. 두 번의 이탈(drifts)이 저의 엄격한 한계선입니다. 여기서 중요한 절제력은 잘못된 세션을 계속해서 "수정"하려는 충동을 참는 것입니다. 깨끗하게 다시 시작하는 것이 비용이 더 적게 듭니다.

/context 및 /stats를 통한 컨텍스트와 사용량 모니터링

저는 이 두 명령어를 끊임없이 관찰합니다.

/context

현재 컨텍스트 창(context window)을 소비하고 있는 요소들—시스템 프롬프트(system prompt), 대화 기록(conversation history), 도구 결과(tool results)—의 내역을 보여줍니다. 만약 도구 결과가 컨텍스트를 비대하게 만들고 있다면, 곧 /compress를 사용할 것임을 인지합니다.

/context detail

항목별 상세 내역을 보여줍니다. 하나의 거대한 파일 읽기가 컨텍스트 창의 40%를 잡아먹고 있을 때 유용합니다.

/stats

사용된 토큰(tokens), API 호출(API calls), 예상 비용(cost estimates) 등 상세한 세션 통계를 제공합니다. 저는 큰 작업을 수행하기 전후에 이를 확인합니다. 이를 통해 지출을 관리하는데, 특히 Qwen Max는 가장 저렴한 모델이 아니기에 더욱 그렇습니다.

이것들을 주시하는 것은 운영 환경(production system)에서 메모리 사용량을 모니터링하는 것과 맞먹는 에이전트적(agentic) 행위입니다. 이를 무시하면 대가를 치르게 될 것입니다.

문서 대신 소스 디렉터리 지정하기

이것은 충분히 논의되지 않는 매우 중요한 생산성 팁입니다.

Qwen이 서드파티 라이브러리(third-party library)를 이해해야 할 때, 기본 접근 방식은 문서(docs) URL을 가져오라고 지시하는 것입니다. 문제는 문서가 불완전하거나, 오래되었거나, 혹은 LLM보다는 인간에게 최적화되어 있는 경우가 많다는 점입니다.

대신 제가 하는 방식은 다음과 같습니다. 라이브러리 소스를 다운로드한 뒤 @를 사용하여 대화의 대상을 해당 소스로 직접 지정하는 것입니다:

@./vendor/upstash-redis/src 파이프라인 API가 어떻게 작동하는지 알려줘

또는 더 깊은 경로를 사용하여:

@./node_modules/@electron/remote/src/main contextBridge 설정에 대해 설명해줘

Qwen은 실제 구현(implementation)을 읽습니다. 문서(docs)를 보고 추측하지 않습니다. 지난 메이저 버전에서 변경된 API 시그니처(API signatures)에 대해 환각(hallucination)을 일으키지도 않습니다.

저는 프로젝트 루트에 vendor/ 폴더를 유지하며, 여기에 중요한 의존성(dependencies)의 소스 코드를 클론하거나 복사해 둡니다. 이렇게 하면 @ 참조가 안정적이고 재현 가능해집니다.

Achu의 경우, 구체적으로 Qwen이 Ollama TypeScript 클라이언트 소스, llava-phi3 모델 통합 코드, 그리고 Electron forge 설정의 일부를 참조하도록 지정했습니다. 제가 받는 답변들은 대략적으로 맞는 수준이 아니라, 실제 데이터에 기반한 정확한(ground-truth accurate) 답변입니다.

/remember와 /dream을 이용한 지속적 메모리 (Persistent Memory)

어떤 정보들은 세션 경계를 넘어 유지되어야 합니다. 저의 선호도, 핵심적인 아키텍처 결정, Qwen이 항상 준수해야 하는 제약 조건 등이 그러합니다. 저는 이러한 것들을 위해 /remember를 사용합니다.

/remember IPC에는 항상 Electron의 contextBridge를 사용해줘. remote 모듈은 절대 사용하지 마.
/remember Achu는 oklch 색 공간을 사용해. 변환 없이 hex 값을 제안하지 마.
/remember 무료 티어 사용자는 하루에 3개의 내보내기(exports)가 가능해. Pro 사용자는 무제한이야.

이 정보들은 Qwen의 메모리 저장소(memory store)에 영구적으로 저장되며, 향후 세션에 자동으로 주입됩니다.

/dream은 자동 메모리 통합(auto-memory consolidation)을 위한 수동 트리거입니다. Qwen의 자동 메모리는 백그라운드에서 실행되지만, 긴 세션 후에 현재 세션에서의 중요한 발견 사항들이 확실히 저장되도록 강제로 통합 과정을 거치고 싶을 때 다음과 같이 실행합니다:

/dream

종료하기 전에 캐시를 디스크에 플러시(flushing the cache)하는 것이라고 생각하면 됩니다.

기억된 내용을 검토하고 관리하기 위해 저는 다음을 사용합니다:

/memory

이 명령은 메모리 관리자(Memory Manager) 대화 상자를 열어 항목을 편집하거나 삭제할 수 있게 해줍니다. 저는 가끔 이를 감사(audit)합니다. 오래된 메모리는 메모리가 없는 것만큼이나 해로울 수 있기 때문입니다.

사이드 질문을 위한 /btw 트릭

이것은 제가 가장 좋아하는 삶의 질(quality-of-life) 향상 명령어입니다.

/btw contextBridge.invoke와 contextBridge.exposeInMainWorld의 차이점이 뭐야?

/btw는 최근 대화 문맥(최대 최근 20개 메시지)과 함께 병렬 API 호출 (parallel API call)을 보내며, 메인 대화에는 전혀 영향을 주지 않고 컴포저 (composer) 상단에 응답을 표시합니다. 메인 세션은 중단 없이 계속됩니다.

저는 다음과 같은 용도로 이를 지속적으로 사용합니다: