Teardown gstack: 개발자가 배울 수 있는 기술

소개

개념과 실용에서는 gstack이 무엇인지, 사용자 관점에서 어떻게 사용하는지 알아보았습니다. 이 노트는 다른 관점에서 작성되었습니다 - 기술 개발자로서, gstack Warehouse 파일을 파일별로 읽은 후 어떤 엔지니어링 설계에서 배우고 배울 가치가 있는지 알아보십시오.

gstack은 단순한 23개의 프롬프트 파일 모음 그 이상입니다. 그 뒤에는 템플릿 생성, 자동 업그레이드, 학습 및 메모리, 점진적인 지침, 다중 플랫폼 적응, 계층화된 테스트 등 완전한 엔지니어링 시스템이 있습니다. 이는 기술 프로젝트를 "사용 가능"에서 "사용하기 쉬운" 것으로 바꾸는 열쇠입니다.

1. SKILL.md는 손으로 쓰지 않습니다 - 템플릿 생성 시스템

gstack의 가장 반직관적인 디자인: **각 SKILL.md는 자동으로 생성되며 직접 편집할 수 없습니다. **

SKILL.md.tmpl (人写)  →  gen-skill-docs  →  SKILL.md (机生)

사람이 작성한 .tmpl 템플릿에는 워크플로 논리와 모범 사례, {{PLACEHOLDER}} 자리 표시자가 포함되어 있습니다. 빌드 스크립트는 소스 코드에서 명령 참조, 브라우저 플래그 목록, 서문 시작 코드 등을 추출하고 이를 자리 표시자에 채워 최종 SKILL.md를 생성합니다.

{{PREAMBLE}}           ← 从 resolvers/preamble.ts 生成的启动代码
{{BROWSE_SETUP}}       ← 浏览器初始化指令
{{COMMAND_REFERENCE}}  ← 从 commands.ts 提取的命令文档
{{SNAPSHOT_FLAGS}}     ← 从源代码常量提取的快照选项

**왜 이러는 걸까요? **

• 문서와 코드는 절대로 동기화되지 않습니다. 명령 참조는 소스 코드에서 생성되며 소스 코드가 변경되면 문서가 자동으로 업데이트됩니다.
• 23개의 스킬이 동일한 서문(약 220라인)을 공유하며, 모든 스킬이 동시에 업데이트됩니다.
• CI는 재생성하는 것을 잊지 않도록 생성된 파일이 만료되었는지 여부를 --dry-run 확인할 수 있습니다.

요점: 여러 기술을 유지 관리하는 경우 기술 간에 공유되는 모든 콘텐츠를 템플릿으로 추출하고 빌드 단계에서 사용하여 최종 파일을 생성해야 합니다. 동일한 콘텐츠의 여러 복사본을 수동으로 동기화하면 조만간 문제가 발생할 수 있습니다.

2. 업그레이드 메커니즘 - 탐지부터 실행까지 완전한 연결

gstack의 업그레이드 시스템은 매우 정교하게 설계되었으며 세 가지 계층으로 나뉩니다.

첫 번째 레이어: 버전 감지

bin/gstack-update-check은 다음을 수행하는 독립형 bash 스크립트입니다.

1. 로컬 VERSION 파일을 읽습니다.
2. 캐시 ~/.gstack/last-update-check 확인(60분 동안 UP_TO_DATE 캐시, 720분 동안 UPGRADE_AVAILABLE 캐시)
3. 캐시가 만료되면 HTTP는 GitHub의 raw.githubusercontent.com/.../VERSION을 요청합니다.
4. 버전 번호를 비교하고 UPGRADE_AVAILABLE <旧> <新>을 출력합니다.

두 번째 레이어: 프리앰블 통합

각 스킬의 SKILL.md 시작 코드의 첫 번째 줄은 버전 감지입니다:

_UPD=$(~/.claude/skills/gstack/bin/gstack-update-check 2>/dev/null || true)
[ -n "$_UPD" ] && echo "$_UPD" || true

즉, 사용자가 스킬을 호출하면 업데이트가 자동으로 감지됩니다. 특별히 업그레이드 명령을 실행할 필요가 없으며 존재감은 없지만 적용 범위는 100%입니다.

세 번째 수준: 점진적 알림 + 자동 업그레이드

새 버전을 감지한 후 사용자를 즉시 방해하지 않지만 점진적인 백오프를 위해 다시 알림 메커니즘(Snooze)을 사용합니다.

• 1차 알림: 24시간 후에 다시 언급해 주세요.
• 2차 알림: 48시간 후에 다시 언급해 주세요.
• 3회 이상 : 7일 이후 다시 언급해주세요.
• 새 버전 릴리스에서는 스누즈 카운터가 재설정됩니다.

사용자는 gstack-config set auto_upgrade true 자동 업그레이드를 활성화하고 확인을 건너뛰어 직접 실행할 수 있습니다.

업그레이드를 수행하면 5가지 설치 유형(글로벌 git, 로컬 git, 공급업체 등)이 구분됩니다. git 설치는 git fetch + reset을 사용하고, 공급업체 설치는 먼저 백업한 다음 교체하고, 실패할 경우 .bak에서 복원합니다. 업그레이드 후에는 프로젝트의 로컬 공급업체 복사본도 자동으로 동기화됩니다.

배울만한 가치가 있는 점:

• "각 통화 감지" 모드는 적용 범위가 매우 높으며 사용자가 감지할 수 없습니다.
• 점진적인 백오프로 빈번한 중단 방지
• 설치 유형을 차별화하고 단일 크기 대신 다양한 업그레이드 전략을 구현합니다.
• 백업 및 복원은 업그레이드 실패로 인해 전체 스킬이 중단되지 않도록 보장합니다.

3. 학습 시스템 - 사용할수록 스킬이 스마트해집니다.

gstack은 가볍지만 효과적인 교차 세션 메모리 시스템을 구현합니다.

스토리지

각 프로젝트에는 추가로 작성된 독립적인 학습 로그(~/.gstack/projects/$SLUG/learnings.jsonl)가 있습니다.

{
  "skill": "review",
  "type": "pitfall",
  "key": "n-plus-one",
  "insight": "这个项目的 User model 有 N+1 查询问题，findAll 要加 include",
  "confidence": 8,
  "source": "observed",
  "files": ["src/models/user.ts"],
  "ts": "2026-04-01T14:30:00Z"
}

자동수집

각 기술이 완료되기 전에 "운영 자체 개선" 링크가 있습니다. 실행 중에 발견된 예상치 못한 실패, 우회 또는 프로젝트 문제가 있는지 여부를 반영하고 모든 내용이 learnings.jsonl에 자동으로 기록됩니다. 사용자가 수동으로 트리거할 필요가 없습니다.

자동 로딩

새 세션이 시작될 때마다 프리앰블은 처음 3개의 신뢰도가 높은 학습 항목을 로드하여 컨텍스트를 주입하여 새 세션이 역사적 지식을 상속할 수 있도록 합니다.

신뢰도 하락

observed 및 inferred 소스의 항목은 30일마다 1포인트씩 감소합니다. 지식 기반을 수동으로 정리할 필요가 없습니다. 오래된 지식은 자연스럽게 사라지고 새로운 관찰이 자연스럽게 그 자리를 차지합니다.

관리 인터페이스

/learn            # 显示最近 20 条
/learn search     # 搜索
/learn prune      # 检测过期条目（引用的文件已删除）
/learn export     # 导出为 markdown 可加入 CLAUDE.md

배울만한 가치가 있는 점:

• 추가 쓰기 전용 설계는 간단하고 안정적이며 동시성이 안전합니다.
• 신뢰도 하락은 유지 관리가 적은 지식 노화 관리입니다. 수동 청소보다 훨씬 효율적입니다.
• 경로 대신 git 원격 URL을 사용하여 프로젝트를 식별하고(gstack-slug을 통해) 다른 위치에 복제하고 재사용할 수 있습니다.
• 프로젝트 간 쿼리를 지원하지만 기본적으로 격리됨

4. 프리앰블 주입 - 스킬의 "미들웨어 레이어"

이것은 gstack의 가장 똑똑한 아키텍처 디자인 중 하나입니다. 각 SKILL.md는 웹 프레임워크의 미들웨어처럼 기능하는 약 220줄의 프리앰블 코드를 공유합니다.

┌─ 更新检测 ──────────────────────────────────┐
│ 会话追踪 (sessions/$PPID)                    │
│ 配置读取 (proactive, skill_prefix, telemetry)│
│ 学习历史加载 (前 3 条高置信度)                │
│ 上下文恢复 (最近的 checkpoint + timeline)     │
│ 路由规则检测                                 │
│ 首次使用引导流程                              │
└──────────────────────────────────────────────┘
         ↓
    Skill 特有逻辑

Preamble의 bash 스크립트는 키-값 쌍(BRANCH: main, PROACTIVE: true)을 출력한 다음 템플릿은 자연어 조건을 사용하여 Claude가 그에 따라 행동을 조정할 수 있도록 합니다.

If PROACTIVE is false, do not invoke skills automatically.
Instead suggest: "I think /skillname might help here -- want me to run it?"

이는 본질적으로 bash 출력을 Claude의 "환경 변수"로 처리하는 것입니다. 즉, 런타임 감지에는 bash를 사용하고 동작 라우팅에는 자연어를 사용합니다.

배울 가치가 있는 점: 여러 기술이 있는 경우 각 기술에 대한 복사본을 작성하는 대신 공유 논리(구성 로딩, 상태 복구, 버전 감지)를 통합된 서문으로 추출해야 합니다.

5. 프로그레시브 부팅 - Sentinel 파일 모드

gstack의 최초 사용자 경험은 세심하게 디자인되었습니다. 각 부팅 단계가 터치 파일(센티넬 파일)을 통해 한 번만 발생하는지 확인하세요.

~/.gstack/.completeness-intro-seen    ← "Boil the Lake" 理念介绍
~/.gstack/.telemetry-prompted         ← 遥测选择（community/anonymous/off）
~/.gstack/.proactive-prompted         ← 主动触发开关
~/.gstack/.routing-prompted           ← CLAUDE.md 路由规则写入
~/.gstack/.welcome-seen               ← 安装欢迎消息

스킬이 시작될 때마다 이러한 파일이 존재하는지 확인하십시오. 그렇지 않은 경우 해당 부팅 및 터치 파일을 표시합니다. 이미 본 단계는 다시 표시되지 않습니다.

배울 가치가 있는 점: 구성에서 "onboarding_step": 3 상태를 유지하는 것과 비교할 때 sentinel 파일은 더 간단하고 안정적입니다. 구성 파일 손상의 영향을 받지 않으며 각 단계는 독립적으로 제어됩니다.

6. SKILL.md 구조 설계 - 3계층 아키텍처

각 SKILL.md는 표준 3계층 구조를 따릅니다.

첫 번째 레이어: YAML Frontmatter

---
name: qa
preamble-tier: 3
version: 0.15.1.0
description: |
  Systematically QA test a web application...
  Use when asked to "qa", "test this site", "find bugs"...
benefits-from: [office-hours]
allowed-tools:
  - Bash
  - Read
  - Write
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "bash ${CLAUDE_SKILL_DIR}/bin/check-careful.sh"
---

주요 분야:

• allowed-tools: 도구 수준 권한 허용 목록, 각 기술은 필요한 도구만 선언합니다.
• benefits-from: 사전 종속성 기술을 명시적으로 선언합니다.
• hooks: 도구가 호출되기 전에 가로챌 수 있는 PreToolUse 후크(예: 신중한 가로채기 rm -rf)
• description: 모든 자연어 트리거 단어를 포함합니다.

레이어 2: 공유 프리앰블 + 일반 규칙

프리앰블 시작 코드 + 음성 정의 + 컨텍스트 복구 + 무결성 원칙 + 검색 우선 순위 + 완료 상태 프로토콜 + 업그레이드 규칙 등 모든 기술은 동일하며 템플릿에서 생성됩니다.

세 번째 레이어: 스킬별 로직

이는 워크플로 정의, 역할 설정, 인지 모델 주입, 상호 작용 게이팅 등 각 기술의 "영혼"입니다.

배울 가치가 있는 점: 3계층 분리를 통해 각 스킬은 고유한 로직에만 집중할 수 있으며, 공유된 부분은 일관성을 위해 프레임워크로 보장됩니다.

7. 신속한 엔지니어링 팁 컬렉션

SKILL.md를 모두 읽은 후 학습할 가치가 있는 즉각적인 디자인 기술은 다음과 같습니다.

아첨 금지 규칙

근무 시간의 시작 모드는 AI의 일반적인 "및 진흙탕" 동작을 명시적으로 금지합니다.

Never say:
- "That's an interesting approach" → take a position instead
- "There are many ways to think about this" → pick one
- "You might want to consider..." → say "This is wrong because..."
- "That could work" → say whether it WILL work

금지어 목록

음성 섹션에는 명확한 금지 단어와 문구가 있습니다.

• 금지된 단어: 탐구, 결정적, 강력함, 포괄적, 미묘함, 중추적, 풍경...
• 금지된 문구: "여기에 핵심이 있습니다", "플롯 반전", "이것을 분석해 보겠습니다"...
• 비활성화된 형식: em 대시(쉼표/마침표로 대체)

이는 LLM에서 흔히 사용되는 "AI 스타일의" 단어이며, 비활성화된 후에 출력이 확실히 더 자연스러워집니다.

인지 모델 주입

각 검토 기술은 서로 다른 사고 체계를 주입합니다.

• CEO 리뷰: 18가지 인지 모델(베조스의 일방향/양방향 문 의사결정, 멍거의 역사고, 잡스의 집중과 뺄셈...)
• Eng Review: 15가지 엔지니어링 관리 패턴("기본적으로 지루함", 폭발 반경 직관, 콘웨이 법칙...)
• 디자인 검토: 12가지 디자인 인식 패턴(서비스로서의 계층 구조, 제약 조건 숭배, "내가 눈치챌까?" 테스트...)

이러한 모드는 AI가 기계적으로 수행하도록 허용하지 않지만 똑똑한 신인에게 이전 AI의 경험 목록을 제공하는 것과 마찬가지로 AI에 사고 프레임워크를 제공합니다.

사양기준

Not "you should test this"
    but `bun test test/billing.test.ts`

Not "this might be slow"
    but "this queries N+1, ~200ms per page load with 50 items"

Not "there's an issue in the auth flow"
    but "auth.ts:47, the token check returns undefined"

신뢰도 교정

검토 기술을 사용하려면 각 발견에 신뢰도 점수가 수반되어야 하며 신뢰도가 낮은 결과는 자동으로 다운그레이드되거나 숨겨집니다.

대화형 게이팅

선박 스킬은 사용자를 멈추고 언제 기다려야 하는지, 언제 자동으로 계속해야 하는지를 정확하게 정의합니다.

Only stop for:
- Tests failing with no obvious fix
- Merge conflicts requiring human judgment
- Unclear which changes to include

Never stop for:
- Normal git operations
- CHANGELOG/VERSION updates
- PR creation

배울 가치가 있는 점: 좋은 기술은 "AI가 모든 것을 수행"하는 것이 아니라 인간-기계 경계를 정확하게 정의하는 것입니다.

8. 상태 관리 - 파일 시스템은 데이터베이스입니다.

gstack의 모든 지속성은 ~/.gstack/에 저장된 파일 시스템을 통해 수행됩니다.

거의 모든 시계열 데이터는 JSONL(행당 하나의 JSON 개체)을 사용하여 추가 방식으로 작성됩니다. 이 선택은 현명합니다.

• 쓰기 자연 동시성 안전성 추가
• 데이터베이스 종속성이 필요하지 않습니다.
• grep / jq을 사용하여 직접 쿼리할 수 있습니다.
• 마지막 줄이 누락될 때까지 손상됨

9. 크로스 스킬 통합 모드

파일전송상품

파일 시스템을 통해 기술 간에 작업 산출물을 전송합니다.

/office-hours → design doc → /plan-ceo-review 读取
/plan-ceo-review → ceo-plans/*.md → /autoplan 读取
/review → reviews.jsonl → /ship 读取并展示 Dashboard
/qa → qa-reports/ → /retro 读取

Review Readiness Dashboard

배송 스킬은 reviews.jsonl을 읽고 게시 전 교차 스킬 검토 상태를 표시합니다.

| Review          | Runs | Last Run    | Status | Required |
| Eng Review      |  1   | 2026-03-16  | CLEAR  | YES      |
| CEO Review      |  0   | —           | —      | no       |
| Design Review   |  0   | —           | —      | no       |

종속성 사전 제안

plan-ceo-review가 디자인 문서가 없음을 감지하면 먼저 /office-hours 실행을 적극적으로 권장합니다.

"No design doc found. /office-hours produces a structured problem statement...
Takes about 10 minutes."
Options: A) Run /office-hours now  B) Skip

시퀀스 예측 사용

Context Recovery는 최근 스킬 사용 순서를 분석하고 다음 단계를 예측합니다.

If pattern repeats (e.g., review → ship → review),
suggest: "Based on your recent pattern, you probably want /ship."

10. 그 외 주목할만한 디자인

후크 시스템

주의, 동결 및 보호의 세 가지 기술은 PreToolUse 후크를 사용합니다. 이는 도구가 호출되기 전에 가로챌 수 있는 유일한 메커니즘입니다.

• 주의: Bash를 가로채고 rm -rf, DROP TABLE, git push --force를 확인하세요.
• 동결: 편집/쓰기를 차단하고 경로가 허용 범위 내에 있는지 확인합니다.
• 가드: 위의 두 가지를 결합합니다.

다중 플랫폼 적응

동일한 템플릿 세트는 --host 매개변수를 통해 다양한 플랫폼에 대한 기술 파일을 생성합니다.

bun run gen:skill-docs --host claude   # Claude Code 格式
bun run gen:skill-docs --host codex    # OpenAI Codex 格式
bun run gen:skill-docs --host kiro     # AWS Kiro 格式
bun run gen:skill-docs --host factory  # Factory Droid 格式

경로와 머리말은 자동으로 조정되며, 스킬 로직은 변경되지 않습니다.

완료 상태 프로토콜

각 기술이 끝나면 표준화된 완료 상태가 출력되어야 합니다.

DONE                — 全部完成，提供证据
DONE_WITH_CONCERNS  — 完成但有顾虑
BLOCKED             — 无法继续
NEEDS_CONTEXT       — 需要更多信息

세 가지 업그레이드 규칙 실패

If you have attempted a task 3 times without success, STOP and escalate.

AI가 무한 재시도 루프에 빠지는 것을 방지합니다.

Diff 기반 테스트 선택

E2E 테스트 비용은 각각 약 $4입니다(Claude 에이전트 시작 필요). 따라서 gstack은 touchfiles.ts을 통해 각 테스트가 의존하는 소스 파일을 선언하고 git diff에 따라 영향을 받는 테스트만 실행합니다.

// test/helpers/touchfiles.ts
{
  "qa-workflow": ["qa/SKILL.md.tmpl", "browse/src/server.ts"],
  "ship-flow": ["ship/SKILL.md.tmpl", "scripts/resolvers/preamble.ts"]
}

요약: 가져갈 수 있는 디자인 원칙

gstack의 엔지니어링 실무에서 Skill 개발자에게 가장 중요한 다음과 같은 설계 원칙을 추출했습니다.

1. 템플릿 생성 > 수동 동기화: 기술 전반에 걸쳐 공유되는 콘텐츠는 템플릿 + 빌드 단계를 사용하여 자동으로 생성되며 복사 및 붙여넣기는 불가능합니다.
2. 패시브 감지 > 액티브 감지: 모든 스킬 호출에 업그레이드 감지가 포함되어 있으며 사용자는 인식하지 못하지만 적용률은 100%입니다.
3. 로그 추가 > 복잡한 데이터베이스: JSONL + 파일 시스템은 간단하고 안정적으로 대부분의 지속성 요구 사항을 충족할 수 있습니다.
4. 프로그레시브 부팅 > 단일 구성: 센티넬 파일을 사용하여 부팅 단계를 제어하며 각 단계는 한 번만 나타납니다.
5. 정확한 게이팅 > 완전 자동: "중지 및 사용자 대기"와 "자동 계속" 사이의 경계를 명확하게 정의합니다.
6. 신뢰도 정량화 > 퍼지 판단: 각 AI 판단에는 신뢰도 점수가 부여되며 낮은 신뢰도는 자동으로 하향 조정됩니다.
7. Time Decay > 수동 정리: 학습 기록에 대한 신뢰도는 시간이 지나면서 쇠퇴하고, 오래된 지식은 자연스럽게 사라집니다.
8. 금지어 목록 > 스타일 가이드: 금지어를 직접 나열하는 것이 "자연스러운 어조를 사용하세요"보다 훨씬 효과적입니다.

관련 자료:

• gstack 개념 — gstack은 무엇이고 어떤 문제를 해결하나요?
• gstack 실무 장 — 설치부터 실행까지 전체 워크플로
• gstack Front-end Skill — 프런트엔드/UI 디자인 스킬 파노라마 및 권장 워크플로
• Claude Skills Concept — 스킬의 기본 메커니즘을 이해합니다.