garagon/nanostack

당신의 AI 에이전트가 코드를 작성합니다. Nanostack은 에이전트가 신뢰할 수 있는 결과물을 배포하도록 보장합니다.

AI 코딩 에이전트를 위한 로컬 배포 워크플로우 하네스 (Local delivery workflow harness).

범위 설정, 계획, 구축, 리뷰, 보안, QA, 배포. 모든 단계는 당신의 디스크에 있는 일반 텍스트 파일로 읽을 수 있는 증거를 남깁니다. 기본 스프린트 (sprint)를 사용하거나, 그 위에 자신만의 워크플로우 스택 (workflow stack)을 구축하세요.

오픈 소스 (Open source). 일반 텍스트 (Plain text) 기술. 로컬 아티팩트 (Local artifacts). 검증된 어댑터 (Verified adapters). Nanostack 클라우드 없음.

개요 · 설치 · 스프린트 (The Sprint) · 시각적 아티팩트 (Visual artifacts) · 확장 · 릴리스 노트 (Release notes) · 스페인어

Garry Tan의 gstack에서 영감을 받았습니다. Nanostack은 에이전트에게 소규모 제품 팀의 작업 방식을 부여합니다. 에이전트는 범위를 질문하고, 계획을 세우고, 코드를 리뷰하며, 보안을 감사하고, 테스트하고, 배포하며, 모든 단계에서 검사 가능한 기록 (paper trail)을 남깁니다. 모든 것은 Apache 2.0 라이선스 하의 일반 텍스트와 로컬 스크립트로 구성되어 있어, 에이전트가 따르는 모든 규칙을 읽을 수 있습니다. Nanostack 클라우드, 데몬 (daemon), 앱 런타임 (app runtime)은 없습니다.

현재 검증된 어댑터: Claude Code, Cursor, OpenAI Codex, OpenCode, 그리고 Gemini CLI. 스킬 파일은 일반 텍스트이므로 다른 에이전트들도 로드할 수 있지만, adapters/ 디렉토리에 검증된 어댑터와 기능 선언이 있는 것은 이 다섯 가지뿐입니다.

최신 릴리스에서 변경된 사항 (커스텀 워크플로우 스택, 시각적 아티팩트, 더 강력한 안전 계약): RELEASE_NOTES.md를 참조하세요.

사용자: 내 앱에 알림 기능을 추가해야 해. 사용자들이 게시물에 달린 답글을 계속 놓치고 있어.
사용자: /think
...

이것이 차이점입니다: 단순한 코드 생성이 아니라, 당신이 검사할 수 있는 배포 루프 (delivery loop)를 제공하는 것입니다.

Nanostack 미사용 시	Nanostack 사용 시
❌ 모호한 프롬프트가 즉시 코드로 변환됩니다.	✅ /think가 아이디어를 간략한 요약, 리스크, 그리고 가장 유용한 최소 시작점으로 변환합니다.
...

• ✅ AI 에이전트를 하루 종일 켜두고도 여전히 배포 속도가 느리다고 느낍니다
• ✅ 단순한 오타가 아니라 범위 이탈 (scope drift)을 잡아내는 리뷰를 원합니다
• ✅ 분기별 한 번이 아니라, 매 배포 전 보안 감사 (security audit)를 원합니다
• ✅ 단순히 파일 목록을 나열하는 것이 아니라, '이유 (WHY)'를 설명하는 PR 설명을 원합니다
• ✅ Claude Code, Cursor, OpenAI Codex, OpenCode, Gemini CLI 전반에서 작동하는 프로세스를 원합니다
• ✅ SaaS에 종속되지 않고, 검사 가능한 형태로 디스크에 저장된 기술 (skills)을 원합니다

아직 확신이 서지 않나요? Examples Library에서 일회성 샌드박스 (sandbox)로 시작해 보세요. 제품을 위험에 빠뜨리지 않고 실제 스프린트를 경험할 수 있습니다.

예시	최적의 용도	스택 (Stack)	소요 시간
starter-todo	신규 및 비기술 사용자	HTML 파일 1개	5-10분
cli-notes	CLI 워크플로	Bash	5-15분
api-healthcheck	백엔드 플로 (flows)	Node stdlib HTTP	10-15분
static-landing	창업자 및 디자이너	정적 HTML/CSS	10-15분
compliance-release	커스텀 워크플로 스택을 구축하는 팀	라이선스 + 개인정보 보호 + 릴리스 게이트 (release gate)	15-30분

각 예시에는 복사-붙여넣기 가능한 프롬프트, 예상 스프린트 흐름, 성공 기준 및 리셋 단계가 포함되어 있습니다. 전체 Examples Library: examples/

.

compliance-release는 고급 과정입니다. 이것은 스타터 앱도 아니고 컴플라이언스 인증도 아닙니다. 여러 개의 커스텀 기술 (skills)이 어떻게 하나의 릴리스 워크플로로 구성될 수 있는지를 보여줍니다.

npx create-nanostack

단 한 번의 명령어로 에이전트를 감지하고, 모든 것을 설치하며, 설정을 실행합니다.

그 다음 에이전트에서 /nano-run을 실행하여 대화를 통해 프로젝트를 구성하세요. 첫 번째 스프린트에서 /think는 전체 파이프라인을 보여주므로 다음에 무엇이 올지 알 수 있습니다.

실제 리포지토리 (repo)에 설치하기 전에 워크플로를 확인하고 싶다면, 위의 샌드박스 예시 중 하나를 사용하세요.

만약 당신이...	여기서 시작하세요
에이전트 워크플로 (agent workflows)가 처음이라면	starter-todo를 시도한 후, /nano-run을 실행하세요
...

당신의 에이전트는 이미 파일을 편집하고 명령어를 실행할 수 있습니다. Nanostack은 에이전트에게 방법론을 제공합니다: 13개의 내장 기술 (built-in skills), 7단계의 기본 스프린트 (default sprint), 그리고 자신만의 워크플로 스택 (workflow stacks)을 구성할 수 있는 프레임워크를 제공합니다.

기본 스프린트는 요청을 범위가 지정되고, 검토되었으며, 보안 점검을 거치고, 테스트된 변경 사항으로 변환하며, 이와 함께 PR (Pull Request)과 스프린트 저널 (sprint journal)을 생성합니다. 각 단계는 구조화된 아티팩트 (artifact)를 작성합니다. 즉, 무엇이 결정되었고 무엇이 점검되었는지를 기록하는 작은 로컬 파일입니다. 이후 단계들은 단순히 채팅 기록에만 의존하는 대신 이 파일들을 읽어 들입니다.

이 방식의 핵심은 아티팩트 우선 전달 (artifact-first delivery)입니다:

• 기술 (Skills)은 일반 텍스트입니다.
• 아티팩트 (Artifacts)는 로컬 JSON입니다.
• 게이트 (Gates)는 배포 전 증거를 검증합니다.
• 시각적 아티팩트 (Visual artifacts)는 로컬 HTML로서 동일한 증거를 렌더링합니다.
• 커스텀 워크플로 스택 (Custom workflow stacks)은 사용자 정의 단계를 통해 동일한 파이프라인을 확장합니다.

Claude Code에서는 Nanostack이 PreToolUse 훅 (hooks)을 통해 워크플로의 일부를 강제할 수 있습니다. 다른 에이전트의 경우, 동일한 워크플로가 가이드된 지침 (guided instructions)으로서 실행됩니다. 호스트별 상세 비교 표는 '어떤 에이전트에서 무엇이 강제되는지 (What enforces on which agent)'를 참조하세요.

내장된 스프린트가 기본 스택입니다:

단계	전문가 (specialist)가 수행하는 작업
01	/think	질문을 통해 당신의 거친 아이디어를 정교화합니다. 가장 작고 유용한 버전을 찾아냅니다.
02	/nano	구현을 계획합니다. 파일 이름, 리스크, 체크리스트를 지정합니다.
03	build	당신 또는 에이전트가 코드를 작성합니다.
04	/review	2회차 코드 리뷰 (code review). 범위 이탈 (Scope drift) 탐지. 기계적인 오류 자동 수정.
05	/security	OWASP A01-A10 감사 + STRIDE 위협 모델링 (threat modeling). A-F 등급 부여.
06	/qa	대상물을 테스트합니다. 브라우저, API, CLI 또는 근본 원인 디버깅 (root-cause debug).
07	/ship	PR 생성, CI 검증, 릴리스 노트, 스프린트 저널 작성. 운영 환경 배포 (Production deployment)는 명시적이며 사용자의 제어 하에 유지됩니다.

Nanostack은 표준을 설명하는 것이 아니라, 표준에 맞춰 적응합니다.

프로필 (Profile)	변경 사항 (What changes)
Guided	평이한 언어, 하나의 다음 동작, 더 안전한 기본값, 숨겨진 전문 용어 없음.
Professional	더 밀도 높은 출력, 더 깊은 트레이드오프 (tradeoffs), 명시적인 파일, 명령 및 리스크.

로컬 모드 (Local mode)는 기본적으로 Guided 언어를 사용합니다. git 프로젝트라도 사용자가 더 간단한 설명을 원한다면 Guided를 사용할 수 있습니다.

문구 규칙은 reference/plain-language-contract.md에 정의되어 있습니다. 프로필을 선택하는 세션 필드는 reference/session-state-contract.md에 정의되어 있습니다.

Nanostack은 에이전트 불가지론적 (agent-agnostic)이지만, 에이전트 호스트 (agent hosts)마다 동일한 제어 지점을 노출하지는 않습니다. adapters/ 디렉토리의 어댑터 (adapter) 파일들이 각 호스트에 대한 신뢰할 수 있는 단일 원천 (source of truth)입니다.

레벨 (Level)	의미 (Meaning)
L0 Guided	스킬 (skill)이 에이전트에게 무엇을 할지 알려주지만, 이를 차단할 수는 없습니다. 또한 호스트가 전혀 제공할 수 없는 기능도 포함됩니다.
L1 Checked	Nanostack이 문제를 감지하고 보고할 수 있지만, 이를 차단할 수는 없습니다.
L2 Guarded	호스트가 동작을 수행하기 전에 nanostack 훅 (hook)을 실행합니다.
L3 Enforced	훅이 동작을 차단할 수 있으며, 호스트가 해당 차단을 준수합니다.
L4 Continuously verified	CI 작업이 모든 변경 사항에 대해 해당 기능을 실행합니다.

호스트별 상세 매트릭스 (Bash guard, Write/Edit guard, phase gate)는 아래의 'What enforces on which agent' 섹션에 기술되어 있습니다.

Nanostack은 도구의 집합이 아니라 하나의 프로세스입니다. 스킬은 스프린트 (sprint)가 진행되는 순서대로 실행됩니다:

/think → /nano → build → /review → /security → /qa → /ship

각 스킬은 다음 스킬로 이어집니다. /nano는 /review가 범위 이탈 (scope drift) 감지를 위해 읽을 아티팩트 (artifact)를 작성합니다. /review는 /security의 결과물과 충돌하는 부분을 잡아냅니다. /ship은 PR을 생성하기 전에 모든 것이 깨끗한지 확인합니다. Claude Code에서는 페이즈 게이트 (phase gate)가 훅 (hook) 레이어에서 파이프라인을 강제합니다: 리뷰, 보안, QA가 최신 아티팩트를 생성할 때까지 git commit이 차단됩니다. 훅을 지원하지 않는 에이전트의 경우, 동일한 게이트가 가이드된 지침 (guided instructions)으로서 실행되므로, 안전성은 에이전트가 이를 따르는지에 달려 있습니다. 'What enforces on which agent'를 참조하세요.

기술 (Skill)	당신의 전문가	역할
/think	제품 발견 (Product discovery)	구축하기 전에 활성화됩니다. 질문을 통해 한 번에 하나씩 거친 아이디어를 정교화합니다. 트레이드오프 (trade-offs)를 고려하여 2~3가지 접근 방식을 탐색합니다. 섹션별로 당신과 함께 설계를 진행합니다. 다음 단계를 읽을 수 있는 요약본을 저장합니다. 가이드형 아키타입 (archetypes), 검색 개인정보 보호 모드 (local_only, private, public), 스프린트 회고를 위한 --retro, 그리고 요약본 완료 후의 --autopilot을 지원합니다.
/nano	엔지니어링 매니저 (Eng Manager)	구현 단계 전에 제품 사양 (Medium scope) 또는 제품 + 기술 사양 (Large scope)을 자동 생성합니다. 웹을 위한 제품 표준 (shadcn/ui), CLI/TUI (Bubble Tea, Rich, Ink, Ratatui)를 지원합니다. 초보자를 위해 CLI를 선호하는 스택 기본값을 제공합니다.
/review	스태프 엔지니어 (Staff Engineer)	2단계 코드 리뷰: 구조적 리뷰 후 적대적 (adversarial) 리뷰를 수행합니다. 기계적인 문제를 자동 수정하고, 판단이 필요한 부분에 대해 질문합니다. 계획 대비 범위 이탈 (scope drift)을 감지합니다. /security와 10개의 충돌 선례를 교차 참조합니다.
/qa	QA 리드 (QA Lead)	기능 테스트 + 시각적 QA (Visual QA). 스크린샷을 찍고 제품 표준에 따라 UI를 분석합니다. 브라우저, API, CLI 및 디버그 모드를 지원합니다. WTF 휴리스틱 (heuristic)은 수정 사항이 회귀 (regressions)를 일으키기 전에 중단합니다.
/security	보안 엔지니어 (Security Engineer)	스택을 자동 감지하고 비밀 정보 (secrets), 인젝션 (injection), 인증 (auth), CI/CD, AI/LLM 취약점을 스캔합니다. 등급별 보고서 (A-F)를 제공합니다. 충돌 감지를 위해 /review와 교차 참조합니다. 모든 발견 사항에는 수정 방법이 포함됩니다.
/ship	릴리스 엔지니어 (Release Engineer)	사전 점검 (Pre-flight) + 리포지토리 품질 체크. PR 생성, CI 모니터링, 스프린트 저널을 수행합니다. 커밋 후에는 로컬 실행, 프로덕션 배포, 또는 완료 여부를 묻습니다. 프로덕션 경로는 호스팅, 도메인, 모니터링, 비용을 안내합니다.

기술 (Skill)	역할
/compound	지식 (Knowledge)
/guard	안전 (Safety)
/conductor	오케스트레이터 (Orchestrator)
/feature	빌더 (Builder)
/nano-run	온보딩 (Onboarding)
/nano-help	참조 (Reference)

모든 변경 사항에 전체 감사가 필요한 것은 아닙니다. /review, /qa, /security는 세 가지 모드를 지원합니다:

모드	플래그	사용 시점
Quick	--quick	오타, 설정(config), 문서(docs). 명백한 사항만 보고합니다.
Standard	(기본값)	일반적인 기능 및 버그 수정.
Thorough	--thorough	인증(Auth), 결제(payments), 인프라(infra). 의심스러운 모든 사항을 보고합니다.

/nano

프로젝트 복잡도에 따라 사양(specs)을 자동으로 생성합니다:

범위	제공 항목
Small (1-3개 파일)	구현 단계(implementation steps)만 제공
Medium (4-10개 파일)	제품 사양(product spec) + 구현 단계
Large (10개 이상 파일)	제품 사양(product spec) + 기술 사양(technical spec) + 구현 단계

제품 사양(product spec)은 문제(problem), 해결책(solution), 사용자 스토리(user stories), 수락 기준(acceptance criteria), 사용자 흐름(user flow), 예외 케이스(edge cases), 범위 외 사항(out of scope)을 다룹니다. 기술 사양(technical spec)은 아키텍처(architecture), 데이터 모델(data model), API 계약(API contracts), 통합(integrations), 기술적 결정(technical decisions), 보안 고려 사항(security considerations), 마이그레이션/롤백(migration/rollback)을 추가합니다.

사양은 구현 전에 승인을 받기 위해 제시됩니다. 사양이 틀리면, 그 이후의 모든 과정이 틀리게 됩니다.

사용자: 클라우드 설정 오류(misconfigurations)를 위한 보안 스캐너를 만들고 싶어요.
S3 버킷이 공개 상태로 방치되어 있거나 IAM 역할(roles)이 너무 광범위한 경우가 계속 발견되고 있습니다. 지난달에는 공개된 버킷 때문에 사고가 발생했습니다.
...

당신은 "보안 스캐너"라고 말했습니다. 하지만 에이전트는 "예방 게이트(prevention gate)를 구축하고 계시군요"라고 답했습니다. 에이전트가 당신의 기능 요청(feature request)이 아니라 당신의 고충(pain)을 들었기 때문입니다. 일곱 개의 명령어로 시작부터 배포(shipped)까지 완료하세요.

모든 /think 실행은 .nanostack/know-how/briefs/에 공유 가능한 마크다운 브리프(markdown brief)를 저장합니다. JSON 아티팩트(artifact)가 아닙니다. 팀원에게 보내거나, 문서에 붙여넣거나, Obsidian에서 열 수 있는 깔끔한 문서입니다.

# Think Brief: S3 공개 액세스 예방 게이트
**날짜:** 2026-04-12
**모드:** Startup
...

브리프는 무엇을 만드는지, 누구를 위한 것인지, 왜 이 범위인지, 그리고 무엇이 잘못될 수 있는지를 답변합니다. 코드를 작성하기 전에 이를 공유하세요.

두 번째 스프린트부터 /think는 마지막 3개의 브리프와 최신 회고(retro)를 읽습니다. 제로 베이스에서 시작하는 대신, 다음과 같은 컨텍스트(context)와 함께 시작합니다: "지난 스프린트: 웹훅 서명 게이트(webhook signature gate), IAM 역할 체크. 회고에서는 속도 제한(rate limiting)을 권장했습니다. 다음으로 진행할 작업은 무엇인가요?"

스프린트(sprint)가 끝난 후, /think --retro를 사용하여 출시된 내용에 대해 회고(reflect)하세요:

You: /think --retro
Agent: Reading sprint data...
Sprint Retro
...

회고(Retro)는 스프린트 저널(sprint journal), 복합 솔루션(compound solutions), 패턴 보고서(pattern report), 그리고 git 메트릭(git metrics, 커밋, 변경된 라인 수, 단계별 사이클 타임(cycle time)을 확인하기 위한 bin/sprint-metrics.sh)을 읽습니다. 이는 앞으로 구축할 것이 아니라, 이미 구축된 것에 대해 동일한 강제 질문(forcing questions)을 적용합니다. 새로운 스프린트를 시작하는 것이 아니라, 독립적인 회고 과정입니다.

아이디어를 논의하고, 브리프(brief)를 승인한 뒤, 그대로 넘어가면 됩니다. 에이전트는 전체 스프린트를 다음과 같이 실행합니다:

/think --autopilot

/think는 대화형(interactive)입니다. 에이전트가 질문을 던지면 사용자가 답변하며, 브리프에 대해 의견을 조율합니다. 승인한 후에는 나머지 모든 과정이 자동으로 실행됩니다:

/nano → build → /review → /security → /qa → /ship

Claude Code에서 단계 게이트(phase gate)는 훅(hook) 레이어에서 파이프라인을 강제합니다. 에이전트가 작업을 "단순함(simple)"으로 판단하여 리뷰(review)나 보안(security) 단계를 건너뛰려 하더라도, 모든 단계에서 최신 아티팩트(artifacts)가 생성될 때까지 git commit은 차단됩니다. 이 훅은 별도의 지시 없이도 커밋을 중단시킵니다. 사전 작업 훅(pre-action hooks)을 지원하지 않는 에이전트의 경우, 동일한 게이트가 에이전트가 읽는 규칙으로서 작동합니다. 게이트는 그 차이를 정직하게 알리며, /nano-doctor가 설치된 환경의 실제 수준을 보고합니다.

Autopilot은 맹목적인 추측이 아니라, 완전한 브리프가 작성된 후에 계속됩니다. /think --autopilot은 항상 브리프를 먼저 생성합니다. 만약 브리프에 필수 필드(value_proposition, target_user, narrowest_wedge, key_risk)가 포함되어 있다면,