Lab 03: gstack으로 이해하는 개인 AI 작업 스택

• 한 사람이 넓은 오너십을 가지고 AI와 일하는 흐름을 이해합니다.
• gstack을 개인 AI 작업 스택의 대표 사례로 읽습니다.
• 반복 절차를 Skill 후보로, 확인 기준을 Hook 후보로 나눕니다.
• Skill, Hook과 Plugin의 차이를 이해하고 기존 Plugin을 활용할 기준을 세웁니다.
• 여러 에이전트를 병렬로 쓸 때 worktree가 필요한 이유를 이해합니다.
• 개인 LLM-Wiki의 프로젝트 구조를 검토하고 다음 자동화 후보를 정리합니다.

Lab 01에서는 자료를 구조화된 결과물로 바꾸는 최소 워크플로우를 만들었습니다. Lab 02에서는 그 결과물과 프로젝트 맥락을 개인 LLM-Wiki에 쌓기 시작했습니다.

이제 질문은 바뀝니다.

한 사람이 AI와 함께 어디까지 넓은 범위를 책임질 수 있는가?

지금은 모델이 부족해서가 아니라, 사람이 결과물 기준과 작업 맥락을 정리하지 못해서 병목이 생기는 경우가 많습니다. 한 사람이 제품, 자료, 코드, 문서, 검토, 배포까지 넓게 오너십을 가지고 AI를 잘 활용하면 생산성은 크게 올라갑니다.

하지만 이것은 AI가 마법처럼 일을 해준다는 뜻이 아닙니다. 사람이 맡은 일을 여러 역할과 절차로 구조화하고, 그 구조를 에이전트가 따라갈 수 있게 만드는 것입니다.

gstack은 Garry Tan이 공개한 오픈소스 AI 소프트웨어 팩토리입니다. GeekNews 소개글에서도 한 사람이 AI 에이전트를 활용해 작은 제품팀처럼 일하는 사례로 소개됩니다.

gstack의 핵심은 Claude Code에 여러 역할 기반 명령과 도구를 붙여, 제품 개발 과정을 하나의 흐름으로 운영하는 것입니다. 공식 README는 gstack을 Claude Code를 가상 엔지니어링 팀처럼 바꾸는 도구로 설명합니다. CEO 리뷰, 엔지니어링 리뷰, 디자인 리뷰, 코드 리뷰, QA, 보안 감사, 릴리즈 같은 역할이 slash command로 구성됩니다.

중요한 것은 명령어가 많다는 점이 아닙니다. 중요한 것은 한 사람이 제품의 넓은 범위를 오너십 있게 다루기 위해 필요한 역할과 기준을 구조화했다는 점입니다.

Think -> Plan -> Build -> Review -> Test -> Ship -> Reflect

우리 수업 관점에서 보면 gstack은 아래 요소들이 합쳐진 사례입니다.

수업 개념	gstack에서 보이는 형태
Skill	/office-hours, /review, /qa, /ship 같은 역할 기반 명령
Hook / Guardrail	/careful, /freeze, /guard, 보안 감사, 실행 전 확인
Plugin	여러 명령, 도구, 설정, 설치 방식을 묶어 에이전트 환경에 붙이는 구조
Worktree	여러 작업을 격리된 작업 공간과 브랜치로 나누는 방식
장기 기억	/learn, 문서 업데이트, 프로젝트별 패턴과 선호 기록

이 워크숍에서 gstack을 그대로 복제하지는 않습니다. 대신 gstack을 보고, 내 프로젝트에 맞는 작은 AI 작업 스택을 직접 설계합니다.

Skill, Hook, Plugin은 모두 에이전트 작업을 확장하는 방식이지만 같은 층위의 말은 아닙니다. 수업에서는 아래처럼 구분합니다.

구분	핵심 질문	작동 방식	이번 Lab의 결과물
Skill	이 일을 어떻게 반복 수행할 것인가	에이전트가 필요할 때 읽는 절차서, 체크리스트, 출력 형식	skills/trend-note-skill.md
Hook	어느 순간에 자동으로 확인하거나 막을 것인가	프롬프트 제출, 도구 실행 전후, 작업 종료 같은 시점에 실행되는 검사·개입	hooks/source-check-hook.md
Plugin	이미 묶여 제공되는 능력을 어떻게 활용할 것인가	Skill, Hook, 도구 연결, 설정, 에이전트 정의가 하나의 패키지로 제공됨	plugin-use-plan.md
gstack	이 묶음을 어떤 일하는 방식으로 운영할 것인가	개인이 제품·자료·코드·검토·배포를 넓게 책임지는 작업 운영 체계	progress.md 검토 기록

정리하면 Skill은 에이전트에게 일을 시키는 방식입니다. 예를 들어 “URL을 읽고 JSON으로 구조화한 뒤 Markdown 노트로 바꿔라”처럼 반복 절차와 산출물 형식을 담습니다.

Hook은 에이전트가 일하는 흐름에서 특정 순간에 자동으로 실행되는 장치입니다. 예를 들어 출처가 없는 요약을 저장하려 할 때 막거나, 파일 변경 후 민감정보가 들어갔는지 검사하는 식입니다.

Plugin은 Skill과 Hook, 도구 연결, 설정을 다른 프로젝트나 팀에서도 붙여 쓸 수 있게 묶은 단위입니다. 하나의 Skill 파일보다 크고, 하나의 자동 검사보다 넓습니다. 다만 수업에서 Plugin을 직접 만드는 것이 핵심은 아닙니다. 이미 기업이나 커뮤니티가 제공하는 Plugin을 잘 고르고, 부족한 부분만 나에게 맞게 Skill과 Hook으로 보완하는 것이 더 현실적인 접근입니다.

gstack은 이 모든 요소를 개인의 작업 운영 방식으로 묶은 사례입니다. 명령어를 많이 모아두는 것이 아니라, 한 사람이 넓은 오너십을 가지고 일하기 위해 필요한 역할, 절차, 검토 기준을 구조화한 것입니다.

도구별 이름과 구현은 달라질 수 있습니다. 중요한 것은 “반복 업무는 Skill로, 자동 확인은 Hook으로, 이미 묶여 제공되는 능력은 Plugin으로, 전체 운영 방식은 gstack으로 본다”는 구분입니다.

이번 Lab에서 만드는 ownership-map.md, trend-note-skill.md, source-check-hook.md는 최종 자동화물이 아닙니다. 각 도구가 제공하는 Skill, Hook, Plugin, Steering, Power를 어떻게 활용할지 판단하기 위한 업무 구조 초안입니다.

중요한 순서는 아래와 같습니다.

내 업무 구조화 -> 제공 Plugin 먼저 확인 -> 필요한 부분만 Skill/Hook 커스텀 -> LLM-Wiki에 운영 기준 기록

즉 수업에서 먼저 하는 일은 특정 도구의 버튼을 누르는 것이 아닙니다. 내가 반복하는 일, 결과물 기준, 멈춰야 할 조건, 사람이 결정해야 할 영역을 설명 가능한 문서로 만드는 것입니다. 그 다음 이미 제공되는 Plugin은 활용하고, 정말 나에게 맞는 기준이 필요한 부분만 Skill과 Hook으로 만듭니다.

도구	주로 쓰는 단위	활용하거나 제작할 수 있는 것	Lab 03에서 연결되는 파일
Claude Code / Claude Desktop	Skill, Plugin, Connector	Skill Directory, skill-creator, gstack 같은 Skill 묶음	skills/trend-note-skill.md, hooks/source-check-hook.md
OpenAI Codex	Skill, Hook, Plugin, AGENTS.md	OpenAI 제공 Plugin, 워크스페이스 Plugin, 개인 Plugin, $skill-creator	skills/trend-note-skill.md, hooks/source-check-hook.md
Kiro	Steering, Skill, Hook, Spec, Power	Agent Steering & Skills, Hook 생성, Power 구성	ownership-map.md, source-check-hook.md
Hermes 등 기타 에이전트	도구별 Skill 또는 설정 묶음	gstack의 host 설치, 프로젝트별 규칙 파일	progress.md

수강생은 모든 도구를 다 배울 필요가 없습니다. 자신이 사용하는 에이전트에서 아래와 같이 요청할 수 있으면 충분합니다.

내 LLM-Wiki의 아래 파일들을 읽고,
이미 제공되는 Plugin으로 해결할 수 있는 것과
내가 직접 Skill/Hook으로 커스텀해야 하는 것을 나눠줘.

읽을 것:
- 10-projects/{project-name}/ownership-map.md
- 10-projects/{project-name}/skills/trend-note-skill.md
- 10-projects/{project-name}/hooks/source-check-hook.md
- 10-projects/{project-name}/progress.md

내가 사용하는 도구:
- Claude Code / Codex / Kiro / Hermes 중 하나

작업:
1. 제공 Plugin으로 바로 처리할 수 있는 일을 찾는다.
2. 내 기준이 필요해서 Skill로 만들 일을 찾는다.
3. 자동 가드레일이 필요해서 Hook으로 만들 일을 찾는다.
4. 당장 만들지 않고 나중에 검토해도 되는 일을 분리한다.
5. 진행 결과를 progress.md에 이어서 기록한다.

이 관점에서 Lab 03의 목적은 “스킬 파일 하나를 예쁘게 작성하기”가 아닙니다. 내 업무 패턴을 축적하고, 이미 제공되는 능력과 나에게 필요한 커스텀 능력을 구분하는 것입니다.

참고: Claude Code Skills, OpenAI Codex Skills, Kiro Steering, Kiro Hooks, Kiro Powers

이 과정의 필수 실습은 아닙니다. 다만 Claude Code를 사용하는 수강생은 실제 gstack을 설치해볼 수 있습니다.

공식 README 기준 요구사항은 Claude Code, Git, Bun v1.0 이상입니다. Windows에서는 Node.js도 필요합니다.

gstack README의 설치 흐름은 크게 두 가지로 나뉩니다. Claude Code 기본 설치와, Codex, Kiro, Hermes 같은 다른 AI 에이전트 호스트에 설치하는 방식입니다.

Claude Code 기본 설치

Claude Code 사용자라면 터미널에서 명령을 하나씩 직접 실행하는 것이 아니라, Claude Code를 열고 설치 요청을 그대로 붙여넣는 방식으로 시작합니다. 그러면 Claude Code가 git clone, ./setup, CLAUDE.md 업데이트, 팀 프로젝트에 추가할지 묻는 단계까지 이어서 처리합니다.

이 경우 gstack은 ~/.claude/skills/gstack 아래에 설치됩니다.

Claude Code를 열고 아래 요청을 붙여넣습니다.

Install gstack: run git clone --single-branch --depth 1 https://github.com/garrytan/gstack.git ~/.claude/skills/gstack && cd ~/.claude/skills/gstack && ./setup

Then add a "gstack" section to CLAUDE.md that says to use gstack skills for browsing, planning, reviewing, QA, release, documentation, careful mode, guardrails, upgrade, and learning workflows.

Then ask whether to add gstack to the current project so teammates get it.

팀 저장소에서 함께 쓰려면 team mode도 사용할 수 있습니다. 이 방식은 현재 repo 안에서 팀원들이 gstack을 자동으로 받을 수 있도록 설정하고 변경을 커밋하는 흐름입니다.

(cd ~/.claude/skills/gstack && ./setup --team) && ~/.claude/skills/gstack/bin/gstack-team-init required && git add .claude/ CLAUDE.md && git commit -m "require gstack for AI-assisted work"

Other AI Agents

Codex, Kiro, Hermes 같은 다른 AI 에이전트에 설치하려면 README의 Other AI Agents 흐름을 사용합니다. 설치 스크립트는 설치된 에이전트를 자동 감지할 수 있습니다.

git clone --single-branch --depth 1 https://github.com/garrytan/gstack.git ~/gstack
cd ~/gstack && ./setup

특정 에이전트를 지정하려면 --host 옵션을 사용합니다. 이번 수업에서 특히 참고할 대상은 아래 네 가지입니다.

에이전트	설치 명령	설치 위치
Claude Code	기본 설치	~/.claude/skills/gstack
OpenAI Codex CLI	./setup --host codex	~/.codex/skills/gstack-*/
Kiro	./setup --host kiro	~/.kiro/skills/gstack-*/
Hermes	./setup --host hermes	~/.hermes/skills/gstack-*/

gstack README는 Claude Code 외에도 Codex CLI, Kiro, Hermes, Cursor 같은 여러 AI 코딩 에이전트 호스트를 지원하는 설치 옵션을 안내합니다. 따라서 이 사례는 특정 도구 하나의 기능 소개라기보다, 에이전트 작업 환경을 Skill과 도구 묶음으로 확장하는 방향을 보여주는 사례로 읽는 것이 좋습니다.

gstack 원본 README는 설치 후 바로 써볼 수 있는 흐름을 제시합니다. 핵심은 명령어를 외우는 것이 아니라, 하나의 작업을 작은 스프린트처럼 흐르게 만드는 것입니다.

Think -> Plan -> Build -> Review -> Test -> Ship -> Reflect

설치 후에는 아래처럼 시작할 수 있습니다.

상황	사용 예시	의미
아이디어가 흐릿할 때	/office-hours	무엇을 만들지 대화하며 문제와 방향을 좁힙니다
제품 방향을 검토할 때	/plan-ceo-review	이 결과물이 정말 만들 가치가 있는지 봅니다
기술 설계를 확인할 때	/plan-eng-review	구현 범위, 위험, 구조를 검토합니다
변경된 브랜치를 검토할 때	/review	코드나 문서 변경의 문제를 찾습니다
실제 화면을 확인할 때	/qa	브라우저 기반으로 동작과 품질을 확인합니다
PR과 릴리즈를 묶을 때	/ship	배포 가능한 형태로 정리합니다
다음 작업에 배움을 남길 때	/learn	프로젝트 패턴과 선호를 기억으로 남깁니다

슬래시 명령어를 직접 하나씩 실행할 수도 있지만, 더 자연스러운 방식은 에이전트에게 목표를 말하고 필요한 gstack 명령을 골라 진행하게 하는 것입니다.

예를 들어 Claude Code에서 아래처럼 요청할 수 있습니다.

gstack을 사용해서 이 프로젝트 아이디어를 작은 스프린트로 진행해줘.

내 의도:
- 만들고 싶은 것: {만들 결과물}
- 사용자: {누가 쓰는가}
- 지금 막힌 점: {불확실한 점}
- 오늘 얻고 싶은 결과: {오늘 끝낼 산출물}

진행 방식:
1. 먼저 /office-hours 관점으로 문제와 방향을 좁혀줘.
2. 그 다음 /plan-ceo-review 관점으로 정말 만들 가치가 있는지 검토해줘.
3. 필요하면 /plan-eng-review 관점으로 구현 위험과 작업 순서를 정리해줘.
4. 내가 확인해야 할 의사결정만 질문으로 남겨줘.
5. 결정된 내용은 LLM-Wiki의 10-projects/{project-name}/progress.md에 이어서 남겨줘.

주의:
- 명령어를 무조건 많이 쓰지 말고, 지금 단계에 필요한 것만 사용해.
- 에이전트가 판단한 내용과 사람이 결정해야 할 내용을 분리해.

작업이 어느 정도 진행된 뒤에는 아래처럼 검토와 기록 중심으로 요청할 수 있습니다.

gstack의 review, qa, learn 흐름을 사용해서 오늘 작업을 마무리해줘.

읽을 것:
- 현재 변경된 파일
- 10-projects/{project-name}/ownership-map.md
- 10-projects/{project-name}/progress.md
- 필요하면 관련 Skill/Hook 후보 문서

작업:
1. /review 관점으로 변경 내용의 문제와 누락을 찾아줘.
2. 화면이나 실행 결과가 있다면 /qa 관점으로 확인할 항목을 제안해줘.
3. 이번 작업에서 다음에도 반복될 패턴을 /learn 관점으로 정리해줘.
4. 결과를 progress.md에 "오늘의 결정, 남은 질문, 다음 에이전트가 읽을 파일"로 남겨줘.

이 흐름은 Lab 03의 실습과 직접 연결됩니다. 우리는 gstack 전체를 그대로 따라 하는 대신, 내가 쓰는 에이전트에게 아래와 같은 작은 작업 스택을 만들게 합니다.

• ownership-map.md: 내가 넓게 책임질 범위
• skills/trend-note-skill.md: 반복 업무를 수행하는 방법
• hooks/source-check-hook.md: 자동으로 확인하거나 막을 기준
• plugin-use-plan.md: 기존 Plugin으로 활용할 것과 직접 만들 것을 나누는 기준
• progress.md: 전체 구조 검토와 다음 자동화 후보 기록

여기서 사람의 역할은 사라지지 않습니다. 사람은 에이전트가 만든 초안을 검토하고, 결과물 기준, 공개 가능성, 프로젝트 방향성을 결정합니다. 에이전트는 파일을 만들고 구조를 제안하지만, 오너십은 사람에게 남아 있습니다.

각 실습이 끝날 때마다 개인 LLM-Wiki의 progress.md도 함께 업데이트합니다. 에이전트의 응답은 대화창 안에만 있으면 흘러가지만, 위키에 남기면 내가 전체 그림을 다시 이해할 수 있고 다음 에이전트가 그 맥락을 읽고 이어갈 수 있습니다.

참고: gstack README Quick start, The sprint

Lab 02에서 만든 개인 프로젝트 폴더를 엽니다. 이번 실습에서는 내가 문서를 처음부터 직접 쓰는 것이 아니라, 내가 쓰는 에이전트에게 프로젝트 맥락을 읽히고 오너십 맵 초안을 만들게 합니다.

에이전트에게 먼저 읽힐 파일은 아래와 같습니다.

LLM-Wiki/
└── 10-projects/
    └── {project-name}/
        ├── README.md
        └── progress.md

에이전트에게 아래처럼 요청합니다.

내 개인 LLM-Wiki 프로젝트 폴더를 읽고, 이 프로젝트의 오너십 범위를 정리해줘.

읽을 것:
- 10-projects/{project-name}/README.md
- 10-projects/{project-name}/progress.md
- 필요하면 00-inbox의 관련 노트

만들 것:
- 10-projects/{project-name}/ownership-map.md
- 10-projects/{project-name}/progress.md에 Lab 03 진행 로그 추가

ownership-map.md에는 아래 항목을 포함해줘.
- 이 프로젝트에서 만들 결과물
- 내가 책임질 범위
- AI에게 맡길 수 있는 일
- 사람이 직접 판단해야 하는 일
- 완료 기준
- 멈춰야 하는 조건

초안을 만든 뒤에는 내가 확인해야 할 질문도 3개 남겨줘.

에이전트가 만든 ownership-map.md는 아래 구조를 갖습니다.

# 오너십 맵

## 이 프로젝트에서 만들 결과물
-

## 내가 책임질 범위
- 기획:
- 자료 조사:
- 작성 또는 구현:
- 검토:
- 공유 또는 배포:

## AI에게 맡길 수 있는 일
-

## 사람이 직접 판단해야 하는 일
-

## 완료 기준
-

## 멈춰야 하는 조건
-

progress.md에는 이번 단계의 진행 상황을 남깁니다.

## Lab 03-1 오너십 맵

### 사용한 에이전트
-

### 에이전트가 제안한 핵심
-

### 내가 수정하거나 확정한 기준
-

### 다음에 에이전트에게 먼저 읽힐 파일
- ownership-map.md
- progress.md

핵심은 내가 모든 일을 직접 한다는 뜻이 아닙니다. 내가 결과물의 기준과 흐름을 설명할 수 있어야 AI에게 일을 맡길 수 있다는 뜻입니다. 에이전트의 응답과 LLM-Wiki에 남은 기록을 함께 보면, 내가 지금 어떤 프로젝트를 어떤 기준으로 운영하려는지 전체 그림을 확인할 수 있습니다.

Skill은 “이 상황에서는 이렇게 일하라”를 담은 작업 패키지입니다. 반복되는 절차, 출력 형식, 참고 기준을 다시 설명하지 않게 해줍니다.

Lab 01에서 했던 URL -> JSON -> Markdown 흐름이나, 내 프로젝트에서 반복할 작업 하나를 에이전트에게 찾게 합니다. 이때 실습 1에서 만든 ownership-map.md를 함께 읽혀야 합니다.

LLM-Wiki/
└── 10-projects/
    └── {project-name}/
        └── skills/
            └── trend-note-skill.md

에이전트에게 아래처럼 요청합니다.

내 프로젝트의 반복 업무 중 Skill 후보로 만들 만한 작업을 찾아줘.

읽을 것:
- 10-projects/{project-name}/README.md
- 10-projects/{project-name}/ownership-map.md
- 10-projects/{project-name}/progress.md
- 필요하면 Lab 01에서 만든 트렌드 노트 예시

작업:
1. 반복해서 수행할 가능성이 높은 업무를 2~3개 제안한다.
2. 그중 이번 Lab에서 다룰 하나를 고르고 이유를 설명한다.
3. 10-projects/{project-name}/skills/trend-note-skill.md 파일을 만든다.
4. progress.md에 어떤 Skill 후보를 만들었고 왜 골랐는지 남긴다.
5. 사람이 확인해야 할 누락 기준을 질문으로 남긴다.

에이전트가 만든 Skill 후보는 아래 구조를 갖습니다.

# Skill 후보: 트렌드 노트 작성하기

## 언제 쓰는가
- URL이나 자료 본문을 나중에 다시 활용할 수 있는 노트로 바꿔야 할 때

## 입력
- URL
- 자료 유형
- 공유 대상
- 흥미로운 이유
- 활용 가능성

## 처리 절차
1. 제목, 저자, 출처를 확인한다.
2. 왜 흥미로운 자료인지 설명한다.
3. 나중에 활용할 수 있는 관점을 적는다.
4. JSON으로 구조화한다.
5. Markdown 노트로 변환한다.

## 출력 형식
- TLDR
- 요약
- 활용 관점
- 출처
- 다음 행동

## 금지사항
- 출처 없는 내용을 사실처럼 단정하지 않는다.
- 원문 저자와 공유자를 혼동하지 않는다.
- 확인하지 않은 수치를 넣지 않는다.

Skill은 특정 도구에만 묶인 개념이 아닙니다. Codex, Claude Code, Kiro, Hermes처럼 어떤 에이전트를 쓰더라도 반복 절차와 출력 형식을 설명할 수 있으면 Skill 후보가 됩니다. 중요한 것은 Skill 파일 자체보다, 에이전트의 응답과 위키 기록을 통해 “이 일을 왜 반복 업무로 보았는가”를 내가 이해할 수 있어야 한다는 점입니다.

progress.md에는 아래 항목을 추가합니다.

## Lab 03-2 Skill 후보

### 에이전트가 제안한 반복 업무 후보
-

### 이번에 고른 Skill 후보
-

### 내가 수정하거나 확정한 절차
-

### 다음에 에이전트에게 먼저 읽힐 파일
- ownership-map.md
- skills/trend-note-skill.md
- progress.md

Hook은 에이전트 실행 흐름의 특정 지점에 붙는 자동 실행 규칙입니다. 실행 전 차단, 실행 후 검사, 응답 전 확인처럼 반드시 지켜야 하는 운영 규칙을 다룹니다.

Hook을 이해할 때 가장 중요한 것은 시점과 역할입니다. 언제 실행되는가, 그 순간 무엇을 확인하거나 알려주는가를 먼저 봐야 합니다.

예시로 먼저 이해하기

Hook 후보를 고를 때는 거창한 자동화부터 생각하지 않아도 됩니다. 내가 자주 겪는 문제, 매번 잊는 확인, 반복해서 에이전트에게 설명하는 맥락을 먼저 떠올리면 됩니다.

아래 예시는 실제 운영하던 Claude 설정에서 가져온 아이디어를 수업용으로 단순화한 것입니다. 개인 경로, 토큰, 프로젝트 전용 문구는 제거했고, LLM-Wiki 중심으로 다시 정리했습니다.

예시 파일은 개별로 확인할 수도 있고, 실습용 패키지로 한 번에 받을 수도 있습니다.

패키지에는 README.md, settings.example.json, 예시 Hook 스크립트 3개가 들어 있습니다.

예시 파일	실행 시점	역할	좋은 이유
llm-wiki-context-inject.example.sh	UserPromptSubmit	새 요청을 보낼 때 현재 LLM-Wiki 프로젝트 기억 위치를 알려줍니다	에이전트가 매번 README.md와 progress.md를 먼저 확인하게 만듭니다
commit-format-check.example.sh	PreToolUse(Bash)	git commit 실행 전에 커밋 메시지 규칙을 검사합니다	팀 협업에서 커밋 맥락을 일정하게 남기게 만듭니다
korean-md-bold-check.example.sh	PostToolUse(Edit/Write/MultiEdit)	Markdown 수정 후 한국어 bold 렌더링이 깨질 수 있는 패턴을 검사합니다	내가 자주 겪는 작은 문제를 자동 점검으로 바꾸는 사례입니다

이 세 파일은 정답 템플릿이 아닙니다. 수강생이 그대로 복사해서 쓰기보다, “이 Hook은 어떤 시점에 어떤 역할을 맡는가”를 이해하는 예시로 봐야 합니다. 실제로 쓸 Hook은 각자의 프로젝트, 에이전트, LLM-Wiki 구조, 협업 규칙에 맞게 다시 설계해야 합니다.

첫 번째 예시는 LLM-Wiki를 자동으로 수정하지 않습니다. 대신 에이전트에게 “현재 작업 기억은 여기 있으니 먼저 읽고, 끝나면 여기에 정리하라”고 알려줍니다. 자동으로 모든 대화를 저장하면 민감한 내용이나 잡음까지 쌓일 수 있으므로, 장기기억은 사람이 다시 이해할 수 있는 요약과 결정 중심으로 남기는 편이 좋습니다.

UserPromptSubmit
  -> LLM-Wiki 프로젝트 경로 확인
  -> README.md와 progress.md 위치를 에이전트에게 알려줌
  -> 작업 종료 전 progress.md에 요약과 다음 파일을 남기도록 요청

두 번째 예시는 실행 전 가드레일입니다. 에이전트가 git commit을 실행하려는 순간 메시지 형식을 확인하고, 규칙을 어기면 실행을 막습니다. 이런 Hook은 팀 프로젝트에서 “커밋은 왜 했는지 알 수 있어야 한다”는 기준을 코드로 바꾼 것입니다.

세 번째 예시는 개인화된 품질 점검입니다. 한국어 문서에서 **"텍스트"** 같은 패턴은 환경에 따라 렌더링이 어색해질 수 있습니다. 이처럼 내가 반복해서 겪은 문제는 좋은 Hook 후보가 됩니다. Hook은 일반론보다 “내가 자주 놓치는 것”에서 출발할 때 가장 쓸모가 큽니다.

짧게 말하면, 일하는 방법은 Skill, 반드시 지켜야 할 운영 규칙은 Hook입니다. Hook 후보는 에이전트가 마음대로 자동화할 영역을 늘리는 문서가 아닙니다. 오히려 자동화해도 되는 기준과 사람이 계속 판단해야 하는 기준을 분리하는 문서입니다.

예시를 실제 환경에 붙일 때는 바로 설치하지 말고 먼저 파일을 읽어봅니다. 확인할 것은 네 가지입니다.

• 어떤 이벤트에서 실행되는가
• 어떤 입력을 읽는가
• 어떤 경우에 차단하는가
• 어떤 내용을 로그나 에이전트 컨텍스트로 내보내는가

Claude Code 기준 설정은 아래처럼 연결됩니다. 경로는 자신의 환경에 맞게 바꿔야 합니다.

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/absolute/path/to/llm-wiki-context-inject.example.sh",
            "timeout": 5
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "/absolute/path/to/commit-format-check.example.sh",
            "timeout": 10
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "/absolute/path/to/korean-md-bold-check.example.sh",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

에이전트에게 직접 요청하기

이제 예시를 본 뒤, 내 프로젝트에서 Hook으로 바꿀 만한 문제를 찾습니다. 예를 들어 자료 요약을 자주 한다면 “출처 없는 요약 저장 차단”, 팀 프로젝트를 자주 한다면 “PR 전 progress.md 갱신 확인”, 문서 작업이 많다면 “표나 링크 깨짐 검사”가 Hook 후보가 될 수 있습니다.

이번 실습에서는 실제 자동 Hook을 바로 구현하지 않아도 됩니다. 먼저 에이전트에게 “어느 순간에 무엇을 자동으로 확인해야 하는가”를 찾게 합니다.

에이전트에게 아래처럼 요청합니다.

방금 만든 Skill 후보와 Hook 예시 3개를 참고해서,
내 프로젝트에 맞는 Hook 후보를 정리해줘.

읽을 것:
- 10-projects/{project-name}/ownership-map.md
- 10-projects/{project-name}/skills/trend-note-skill.md
- 10-projects/{project-name}/progress.md
- 필요하면 다운로드한 hook-examples/README.md와 예시 스크립트 3개

작업:
1. 이 Skill이 실패하거나 위험해지는 지점을 찾는다.
2. 각 위험 지점이 어떤 실행 시점에 가까운지 나눈다.
   - UserPromptSubmit: 요청 시작 시 주입하거나 확인할 것
   - PreToolUse: 도구 실행 전에 막거나 확인할 것
   - PostToolUse: 파일 수정 또는 도구 실행 후 검사할 것
   - Stop: 작업 종료 시 기록하거나 경고할 것
3. 사람이 계속 결정해야 하는 항목은 자동화하지 말고 분리한다.
4. 10-projects/{project-name}/hooks/source-check-hook.md 파일을 만든다.
5. progress.md에 Hook 후보를 만든 이유와 사람이 확정한 기준을 남긴다.

에이전트가 만든 Hook 후보는 아래 구조를 갖습니다.

# Hook 후보: 출처와 공개 가능성 확인

## 해결하려는 반복 문제
- 자료를 정리할 때 출처, 공유 대상, 공개 가능성 확인을 자주 놓친다.

## 실행 시점별 후보

### UserPromptSubmit
- LLM-Wiki 프로젝트 README.md와 progress.md 위치를 알려준다.

### PreToolUse
- 출처 없는 자료를 최종 노트로 저장하려는 경우 막는다.
- 공개하면 안 되는 내부 정보가 포함된 경우 막는다.

### PostToolUse
- TLDR 개수가 기준에 맞는지 확인한다.
- 출처가 노트 하단에 남아 있는지 확인한다.
- 다음 행동이 적혀 있는지 확인한다.

### Stop
- 작업 종료 전 progress.md에 오늘 한 일과 다음 파일을 남겼는지 확인한다.

## 사람이 결정할 것
- 이 자료를 실제 프로젝트에 쓸지
- 공개 가능한 표현인지
- 더 조사해야 하는지

progress.md에는 아래 항목을 추가합니다.

## Lab 03-3 Hook 후보

### 참고한 예시
- llm-wiki-context-inject.example.sh
- commit-format-check.example.sh
- korean-md-bold-check.example.sh

### 에이전트가 발견한 위험 지점
-

### 실행 시점별 Hook 후보
- UserPromptSubmit:
- PreToolUse:
- PostToolUse:
- Stop:

### 사람이 계속 판단할 항목
-

### 다음에 에이전트에게 먼저 읽힐 파일
- skills/trend-note-skill.md
- hooks/source-check-hook.md
- progress.md

Plugin은 하나의 작업 절차를 직접 작성하는 것이 아닙니다. 이미 잘 만들어진 기능 묶음을 에이전트 환경에 붙여 쓰는 방식에 가깝습니다.

예를 들어 Codex의 Plugin 화면에는 문서, PDF, 스프레드시트, 발표자료, GitHub, Google Drive, Gmail, Slack, Notion 같은 작업 도구가 이미 제공됩니다. 이런 기능을 직접 Skill과 Hook으로 다시 만드는 것은 속도가 느리고 유지보수도 어렵습니다.

따라서 이번 단계의 핵심은 무엇을 직접 만들지 결정하는 것이 아니라, 무엇은 이미 제공되는 Plugin으로 처리하고, 무엇만 나에게 맞게 커스텀할지 구분하는 것입니다.

이미 제공되는 기능
  -> Plugin으로 활용

내 업무 방식과 결과물 기준
  -> Skill로 정리

반복 실수와 필수 확인
  -> Hook으로 가드레일화

이 구분은 속도 측면에서도 중요합니다. 초기에는 모든 것을 직접 Skill과 Hook으로 만들어야 하는 경우가 많았지만, 지금은 에이전트에 기본 내장되거나 기업이 Plugin으로 제공하는 기능이 빠르게 늘고 있습니다. 잘 만들어진 것은 가져다 쓰고, 내 도메인과 내 업무 패턴에 맞는 부분만 커스텀하는 편이 더 현실적입니다.

에이전트에게 아래처럼 요청합니다.

지금까지 만든 오너십 맵, Skill 후보, Hook 후보를 읽고
내 프로젝트의 Plugin 활용 전략을 정리해줘.

읽을 것:
- 10-projects/{project-name}/ownership-map.md
- 10-projects/{project-name}/skills/trend-note-skill.md
- 10-projects/{project-name}/hooks/source-check-hook.md
- 10-projects/{project-name}/progress.md

작업:
1. 이미 제공되는 Plugin으로 해결할 수 있는 일을 찾는다.
2. 직접 Skill로 만들어야 하는 반복 업무를 찾는다.
3. Hook으로만 해결해야 하는 가드레일을 찾는다.
4. 아직 만들지 말고 나중에 검토할 항목을 분리한다.
5. 10-projects/{project-name}/plugin-use-plan.md 파일을 만든다.
6. progress.md에 판단 기준과 다음 행동을 남긴다.

에이전트가 만든 plugin-use-plan.md는 아래 구조를 갖습니다.

# Plugin 활용 전략

## 이 프로젝트에서 필요한 외부 능력
- 웹 검색 또는 브라우저 확인:
- 문서/PDF 읽기:
- 스프레드시트 정리:
- GitHub 이슈/PR 확인:
- Notion 또는 Google Drive 연결:

## 이미 제공되는 Plugin으로 활용할 것
- GitHub Plugin: 이슈, PR, CI 상태 확인
- Google Drive 또는 Documents Plugin: 자료 문서 읽기와 정리
- PDF Plugin: PDF 자료 읽기와 핵심 추출

## 직접 Skill로 만들 것
- 내 방식의 트렌드 노트 작성 절차
- 내 프로젝트의 결과물 템플릿
- 내가 반복해서 쓰는 검토 순서

## Hook으로 만들 것
- 출처 없는 요약 저장 차단
- 작업 종료 전 progress.md 갱신 확인
- 커밋 메시지 규칙 확인

## 지금 만들지 않을 것
- 이미 Plugin으로 충분히 되는 기능
- 한 번만 쓸 가능성이 높은 자동화
- 아직 기준이 명확하지 않은 작업

## 다음 행동
-

이때 progress.md는 전체 그림을 보는 대시보드 역할을 합니다. 에이전트의 응답과 ownership-map.md, trend-note-skill.md, source-check-hook.md, plugin-use-plan.md를 함께 보면 내가 어떤 방식으로 AI 작업 스택을 구성하고 있는지 이해할 수 있습니다.

progress.md에는 아래 항목을 추가합니다.

## Lab 03-4 Plugin 활용 전략

### Plugin으로 활용할 것
-

### 직접 Skill로 만들 것
-

### Hook으로 만들 것
-

### 지금 만들지 않을 것
-

### 다음 행동
-

AI 에이전트는 말로만 일하는 것이 아니라 실제 파일을 읽고 수정합니다. 그래서 한 사람이 여러 에이전트를 동시에 쓰기 시작하면, 곧바로 파일 충돌 문제가 생깁니다.

예를 들어 한 에이전트는 프로젝트 README를 고치고, 다른 에이전트는 같은 README에 참고 자료를 추가할 수 있습니다. 같은 폴더에서 진행하면 변경이 섞이고, 어떤 결과가 누구의 작업인지 알기 어려워집니다.

왜 AI 작업에서 유용한가

여러 에이전트를 동시에 쓰는 상황에서는 사람이 더 넓은 오너십을 가지는 대신, 각 에이전트가 맡은 작업 범위를 명확히 나눠야 합니다. 이때 worktree는 아래 문제를 줄여주는 운영 방식이 됩니다.

문제	Worktree를 쓰는 이유
같은 파일을 여러 에이전트가 동시에 수정함	작업 폴더와 브랜치를 분리해 변경 범위를 구분합니다
한 에이전트의 실험이 전체 작업 폴더를 망가뜨림	실패한 작업은 해당 worktree에서만 정리할 수 있습니다
서로 다른 접근을 비교하고 싶음	같은 출발점에서 에이전트별 결과를 나란히 만들 수 있습니다
지금 하던 작업을 멈추지 않고 다른 일을 해야 함	현재 폴더를 그대로 둔 채 새 폴더에서 별도 브랜치를 시작합니다

즉 worktree는 에이전트를 많이 쓰기 위한 장식이 아니라, 작업의 격리, 비교, 통합을 가능하게 만드는 운영 방식입니다.

Branch와 무엇이 다른가

Git branch는 작업의 버전 흐름을 나누는 기능입니다. 반면 git worktree는 작업하는 폴더 자체를 나누는 기능입니다.

일반적인 branch 작업에서는 하나의 폴더 안에서 브랜치를 바꿔가며 일합니다.

git switch feature-a
# feature-a 작업

git switch feature-b
# 같은 폴더에서 feature-b 작업

이 방식은 순차적으로 작업할 때는 충분합니다. 하지만 브랜치를 바꿀 때마다 같은 폴더의 파일 상태가 바뀌기 때문에, 작업 중인 변경이 남아 있거나 에이전트가 아직 수정 중이면 전환이 불편해집니다.

worktree를 쓰면 같은 저장소를 여러 폴더로 열어두고, 각 폴더가 서로 다른 브랜치를 담당합니다.

my-project/          main 또는 현재 작업
my-project-a/        feature-a 브랜치
my-project-b/        feature-b 브랜치

이제 my-project-a에서는 한 에이전트가 작업하고, my-project-b에서는 다른 에이전트가 작업하고, 원래 my-project에서는 사람이 결과를 확인할 수 있습니다.

구분	Branch	Worktree
나누는 것	Git 이력의 흐름	실제 작업 폴더
작업 방식	한 폴더에서 브랜치 전환	여러 폴더에서 각 브랜치 동시 작업
장점	가볍고 기본적	병렬 작업, 에이전트 분리, 실험 격리에 유리
주의할 점	전환 시 작업 상태가 섞일 수 있음	폴더가 늘어나 관리 기준이 필요함

따라서 혼자 순차적으로 작업하면 branch만으로 충분합니다. 여러 에이전트나 여러 실험을 동시에 진행한다면 worktree가 더 적합합니다.

Worktree를 한 문장으로 이해하기

git worktree는 하나의 Git 저장소를 여러 작업 폴더로 동시에 열어두는 기능입니다.

일반적으로는 하나의 로컬 폴더에서 브랜치를 바꿔가며 작업합니다. 하지만 worktree를 쓰면 같은 저장소를 기반으로 하면서도, 작업 A는 A 폴더에서, 작업 B는 B 폴더에서, 각각 다른 브랜치로 진행할 수 있습니다.

하나의 원본 저장소
  ├─ main 작업 폴더
  ├─ agent-a 작업 폴더 / branch: glen/codex/readme-intro
  └─ agent-b 작업 폴더 / branch: glen/kiro/source-list

중요한 점은 worktree가 단순히 폴더를 복사하는 방식이 아니라는 것입니다. Git 기록은 같은 저장소를 공유하되, 각 작업 폴더는 서로 다른 브랜치와 작업 상태를 가집니다.

어떻게 활용되는가

실제 흐름은 아래와 같습니다.

1. 사람이 전체 목표와 완료 기준을 정합니다.
2. 작업을 서로 독립적인 단위로 나눕니다.
3. 각 작업마다 브랜치 이름과 worktree 폴더를 정합니다.
4. 각 에이전트는 자기 worktree 폴더 안에서만 작업합니다.
5. 작업 결과는 커밋, PR, 또는 비교 검토를 통해 main 작업으로 통합합니다.
6. 개인 LLM-Wiki에는 어떤 에이전트가 어떤 폴더에서 무엇을 했는지 기록합니다.

이때 사람의 역할은 사라지지 않습니다. 사람은 목표, 범위, 통합 기준, 충돌 가능성을 정하는 운영자가 됩니다.

에이전트에게 설계를 요청하기

아래 프롬프트를 사용해 지금 프로젝트에서 worktree가 필요한 작업을 먼저 나눠봅니다.

내 프로젝트에서 동시에 진행할 수 있는 작업을 worktree 기준으로 나눠줘.

조건:
- 같은 파일을 동시에 수정하지 않도록 작업을 분리한다.
- 각 작업마다 브랜치 이름, worktree 폴더 이름, 맡길 에이전트, 기대 결과물을 정한다.
- 사람이 마지막에 통합할 기준과 충돌 가능성이 있는 파일을 따로 적는다.
- 결과는 내 LLM-Wiki의 현재 프로젝트 폴더에 worktree-plan.md로 저장할 수 있게 작성한다.
- 실제 git worktree 명령은 내가 승인하기 전에는 실행하지 않는다.

명령어로 보면

git worktree add ../my-project-agent-a -b glen/codex/readme-intro
git worktree add ../my-project-agent-b -b glen/kiro/source-list

결과는 이렇게 나뉩니다.

my-project/             main 작업 공간
my-project-agent-a/     README 소개 작성 브랜치
my-project-agent-b/     출처 목록 작성 브랜치

작업이 끝난 뒤에는 목록을 확인합니다.

git worktree list

필요 없어진 worktree는 작업이 커밋되었는지 확인한 뒤 정리합니다.

git worktree remove ../my-project-agent-a

worktree는 강력하지만 모든 작업에 필요한 것은 아닙니다. 작업이 작고 파일 충돌 가능성이 낮다면 브랜치 하나로 충분할 수 있습니다. 여러 에이전트가 동시에 실제 파일을 수정하거나, 서로 다른 접근을 비교해야 할 때 worktree를 사용합니다.

개인 LLM-Wiki에 worktree-plan.md를 만듭니다.

# Worktree 병렬 작업 설계

## 목표
-

## 작업 A
- 브랜치:
- 폴더:
- 맡길 에이전트:
- 맡길 일:
- 결과물:

## 작업 B
- 브랜치:
- 폴더:
- 맡길 에이전트:
- 맡길 일:
- 결과물:

## 사람이 통합할 기준
-

## 충돌 가능성이 있는 파일
-

시간이 충분하면 위 계획 중 하나만 골라 실제 worktree를 만들어봅니다.

마지막 단계는 새 Markdown 파일을 하나 더 만드는 것이 아닙니다. 지금까지 만든 파일과 폴더 구조가 실제로 내 작업 방식을 설명하고 있는지 검토합니다.

이때 검토는 두 방향으로 진행합니다.

Obsidian에서 직접 보기

먼저 Obsidian으로 개인 LLM-Wiki를 열고, 현재 프로젝트 폴더를 직접 살펴봅니다. 파일 이름보다 중요한 것은 내 일의 패턴이 보이는가입니다.

아래 항목을 눈으로 확인합니다.

• 00-inbox에는 아직 정리되지 않은 자료가 남아 있는가
• 10-projects/{project-name}에는 지금 프로젝트의 맥락이 모여 있는가
• progress.md를 보면 현재 상태와 다음 작업을 이어갈 수 있는가
• ownership-map.md는 내가 넓게 책임질 범위를 설명하는가
• skills/, hooks/, plugin-use-plan.md, worktree-plan.md가 서로 따로 놀지 않는가
• Obsidian 링크를 통해 관련 문서가 연결되어 있는가

Obsidian은 사람이 보는 프론트엔드에 가깝습니다. 같은 파일을 에이전트가 읽으면 작업 맥락을 이어가기 위한 백엔드 기억처럼 작동합니다.

에이전트에게 보고받기

다음으로 내가 쓰는 에이전트에게 현재 LLM-Wiki 프로젝트 폴더를 읽게 하고, 수정하지 말고 먼저 보고만 받습니다.

내 LLM-Wiki의 현재 프로젝트 폴더를 읽고 Lab 03 산출물을 검토해줘.

수정하지 말고 먼저 보고만 해줘.

확인할 것:
1. 현재 폴더와 파일 구조 요약
2. ownership-map, skill, hook, plugin-use-plan, worktree-plan의 역할
3. 서로 연결되지 않은 문서나 누락된 결정
4. 내가 반복해서 하는 일의 패턴
5. Skill로 만들 만한 것
6. Hook으로 막아야 할 실수
7. Plugin으로 대체할 수 있는 것
8. Worktree가 필요한 상황
9. 다음에 내가 정리하거나 자동화할 후보

마지막에는 "이 LLM-Wiki가 에이전트의 작업 기억으로 충분한가?"를 기준으로 개선점을 제안해줘.

보고를 받은 뒤에는 바로 모든 제안을 반영하지 않습니다. 사람이 판단해서 다음 작업으로 남길 것만 progress.md에 기록합니다.

## Lab 03 검토 기록

### 현재 구조에서 이해되는 것
-

### 연결이 부족한 문서
-

### 반복되는 내 작업 패턴
-

### 다음에 Skill로 만들 후보
-

### 다음에 Hook으로 막을 후보
-

### Plugin으로 활용할 것
-

### Worktree가 필요한 상황
-

### 다음 행동
-

이 마무리의 목표는 정답 구조를 만드는 것이 아닙니다. 내가 어떤 방식으로 AI와 일하고 있는지, 다음 에이전트가 어디서 맥락을 읽고 이어가야 하는지 확인하는 것입니다.