전편에서 제안한 원칙들을 어떻게 팀 프로젝트에 적용하는지에 대해 Claude Code Plugin / Skills / Hooks를 이용하여 구체적인 예시를 살펴본다.
케이스: LLM의 작업 진행사항을 이슈 트래커와 동기화하기
언젠가 AI의 개발 산출물이 인간의 수준을 아득히 뛰어넘는 날이 오면 더 이상 작업 이력을 추적할 필요가 없어지는 시점이 올지도 모른다.
하지만 인간지능과 인공지능이 공동의 산출물을 함께 작업하는 현시점에서는 기존의 방식대로 작업 계획을 수립하고, 이력을 추적하는 방식이 아직까지는 유효하다. 다만, 기존의 협업 방식이 코딩에이전트의 신속한 작업흐름의 병목이 될 소지가 있으므로 인간과 AI가 조화롭게 협업할 수 있는 방안을 모색해야 한다.
이 글에서는 기존 작업 이력 추적 방식을 유지하면서도 코딩 에이전트의 병목을 최소화하는 방법을 Claude Code의 Plugin, Skills, Hooks 활용한 예제를 통해 살펴본다.
기존 SW 개발 방식.
일감 등록 → 공유/회의 → 업무 배분 → 개발
일반적인 소프트웨어 개발에서 협업은 업무 관계자 간 공유를 전제로 한다. 온/오프라인에서 컨텍스트를 공유, 업무 이해를 바탕으로 일감을 배분한다.
커뮤니케이션은 코스트가 큰 작업이지만 업무의 시작점과 범위를 명확히 하고 팀 전체의 추적성을 높이기 위해 필수적이다.
그래서 협업 문화가 고도화된 조직에서는 비동기적으로 컨텍스트를 공유, 커뮤니케이션 비용을 최소화한다.
코딩 에이전트와의 SW 개발 방식.
목적 공유 → 스펙 구체화 → 구현 계획 수립 → 개발
반면 코딩 에이전트와의 개발은 Local Session 내에서 독자적으로 이뤄진다. 개발자는 에이전트에게 목적을 전달하고, 대화를 통해 스펙을 구체화하며, 구현 계획을 수립한 뒤 바로 개발에 들어간다. 기존 협업 방식에서 팀 회의나 이슈 트래커가 담당하던 기획과 계획 수립이, 개발자와 에이전트 사이의 로컬 세션으로 대체된다.
문제는 이 과정이 외부로 공유되지 않는다는 것이다. “왜 이런 설계를 선택했는지”, “어떤 대안을 검토했는지”, “구현 중 어떤 제약을 만났는지” 등등의 모든 컨텍스트가 대화창 안에만 존재한다. 세션이 종료되면 컨텍스트는 휘발되며 다른 팀원은 최종 결과물만 볼 수 있을 뿐, 결과물에 이르기까지의 의사결정 과정은 알 수 없다.
협업과 지속 가능성이 없는 프로젝트라면 컨텍스트의 공유는 불필요하기에 별 문제가 되지 않을 것이다. 하지만 지속적인 유지보수와 개선이 필요한 팀 프로젝트라면 과정의 가시성을 갖추어야 한다.
두 방식의 충돌
협업 문화가 고도화되지 않은 조직의 워크플로우에 코딩 에이전트를 도입한다면 AI의 압도적인 구현 속도를 프로세스가 따라가지 못할 것이다. 일감등록, 업무배분, 회의 등 모든 단계가 병목이 된다.
반면, 코딩 에이전트와의 개발 방식대로 Local Session 내에서 모든 작업을 계획하고 처리, 결과물만 공유하도록 내버려둔다면 팀단위의 의사결정을 파편화된 Local Session 들에게 위탁하는 결과를 낳게 될 것이다.
해결책 모색: 이슈 트래커-코딩 에이전트 동기화
워크플로우 개선에 앞서 가장 먼저 할 일은 협업 문화를 비동기적으로 개선하는 것이다.
GitHub Engineering의 비동기 커뮤니케이션 원칙처럼, 문서와 이슈 기반으로 의사결정이 이루어지는 문화가 전제되어야 한다. 정례적, 정기적으로 열리는 회의에서 상정되는 아이템이 일감이 되는 워크플로우는 코딩에이전트의 역량에 병목이 된다.
비동기 협업 문화가 갖춰졌다면, 다음 단계는 로컬 세션에 갇힌 코딩 에이전트의 작업 이력을 이 흐름에 자연스럽게 합류시키는 것이다.
Linear 이슈 트래커
이 글에서는 이슈 트래커로 Linear를 사용한다. Linear를 선택한 이유는 Opinionated issue tracker이기 때문이다. Opinionated software란 특정 use case에 맞게 purpose-built된 소프트웨어를 의미한다. Linear의 공동창업자 Jori Lallo는 Figma 블로그 인터뷰에서 이렇게 설명한다:
“We design it so that there’s one really good way of doing things. Flexible software lets everyone invent their own workflows, which eventually creates chaos as teams scale.”
자유도가 높은 도구는 모든 사람이 각자의 워크플로우를 만들어내고, 팀이 커질수록 혼란이 가중된다. Linear는 이슈 상태, 워크플로우, 브랜치 네이밍(gitBranchName), GitHub 연동 방식이 사전 정의되어 있고, 사용자가 이 흐름을 따르도록 유도한다. 이런 설계는 코딩 에이전트와의 통합에 유리하다. 워크플로우가 명확하게 정의되어 있으면, 에이전트에게 “Linear 방식대로 해”라고 지시하는 것만으로 일관된 결과를 기대할 수 있다. 선택지가 많으면 에이전트도 혼란스럽다.
GitHub-Linear Integration
Linear와 GitHub 연동은 물 흐르듯 매끄럽다. 몇 가지 규칙만 따르면 별도의 작업 없이 자동으로 동기화된다. GitHub + Linear integration을 설정하면 PR 자동 연결과 머지 시 이슈 상태 동기화가 활성화된다.
- 이슈 ID 기반 브랜치 생성
- Linear 이슈 화면에서
Copy git branch name액션을 쓰면,username + issue ID + title처럼 Linear – GitHub 간 연동을 위한 ID 정보를 포함한 브랜치 이름을 바로 만들어 GitHub에서 쓸 수 있다. 이 포맷은 GitHub 인테그레이션 설정에서 팀 규칙에 맞게 변경 가능하다.
- Linear 이슈 화면에서
- PR 관리 (이슈 ↔ PR 자동 링크)
- 브랜치 이름이나 PR 제목에 이슈 ID를 포함하면 PR 생성 시 자동으로 Linear 이슈와 연결되고, PR 본문/커밋 메시지에
Fixes ENG-123같은 “magic word + 이슈 ID”를 쓰면 여러 PR·커밋을 하나의 이슈에 링크할 수 있다.
- 브랜치 이름이나 PR 제목에 이슈 ID를 포함하면 PR 생성 시 자동으로 Linear 이슈와 연결되고, PR 본문/커밋 메시지에
- Magic Words
- PR 본문이나 커밋 메시지에
Fixes ENG-123같은 형식으로 이슈 ID 앞에Fixes,Closes,Resolves같은 magic word를 쓰면 해당 PR/커밋이 머지될 때 Linear 이슈가 자동으로 Done 상태로 변경된다. 여러 이슈를 한꺼번에 닫을 수도 있다.분류Magic words (대소문자 무시)Linear에서의 효과사용처예시Closing (머지 후 Issue 자동 완료)close, closes, closed, closing, fix, fixes, fixed, fixing, resolve, resolves, resolved, resolving, complete, completes, completed, completingPR/MR 머지 시 ‘Done’으로 이슈 상태 변경PR/MR descriptionFixes ENG-123Non-closing / Contributing (참조 링크)ref, references, part of, related to, contributes to, towards머지 후에도 이슈 상태 변경 안됨PR/MR descriptionRelated to ENG-123
- PR 본문이나 커밋 메시지에
- 이슈 상태 자동 관리
- GitHub PR이 draft → open → merged 로 이동할 때, 팀별 워크플로 설정에 따라 Linear 이슈 상태를 In Progress / Done 등으로 자동으로 옮길 수 있다. PR revert 시 이슈를 다시 여는 동작도 지원한다.
- GitHub Issues 동기화(선택)
- 필요하면 특정 리포지토리의 GitHub Issues를 Linear 팀과 연결해, 새로 생성되는 이슈의 제목·설명·상태·라벨·assignee·댓글 등을 양방향으로 동기화할 수 있다.
시도 1: linear mcp를 이용한 이슈 트래커 동기화
MCP(Model Context Protocol)는 “로컬 세션에서 만든 계획을 Linear에 바로 반영”하는 가장 직관적인 방법이다. 개발자는 Claude Code와 대화하며 구현 계획(체크리스트/작업 단위)을 만들고, 그 내용을 바탕으로 Linear MCP(Multi-Client/Model Context Protocol) 툴 호출을 명시적으로 지시해서 이슈를 생성/갱신한다.
진행 흐름
1) 목적/스펙 합의: Claude Code와 대화로 요구사항과 범위를 정리한다.
2) 구현 계획 작성: 구현 계획을 TODO/체크리스트 형태로 만든다.
3) Linear 이슈 반영(수동 트리거): linear mcp를 이용하여 지금까지의 구현 계획을 바탕으로 Linear에 이슈를 만들고 업데이트할 것을 지시한다.
4) 개발 진행 중 동기화(반복): 진행 상황이 바뀔 때마다(작업 착수/PR 생성/막힌 점 발생/완료) 다시 MCP 호출을 시켜 상태/코멘트/체크리스트를 업데이트한다.
Linear MCP 사용례
MCP 사용법은 어렵지 않다. 아래와 같이 “어떤 이슈를 어떤 내용으로 만들지/바꿀지”를 구체적으로 기술하여 Tool call을 유도하면 된다.
- 이슈 생성: 제목/설명/우선순위/라벨/담당자/팀/프로젝트 등을 포함해 생성
- 이슈 업데이트: 상태(In Progress/Done), 설명(계획 상세), 코멘트(결정사항/제약/진행상황) 등을 갱신
이슈 생성 예시
지금까지 정리한 구현 계획을 Linear에 반영해줘.
- 팀: ENG
- 프로젝트: Agent Workflow
- 이슈 제목: "Claude Code Hooks로 Linear 동기화 자동화"
- 설명에는 아래 계획을 체크리스트로 포함
- 우선순위 P2, 라벨: agenticai, tooling
이슈 업데이트 예시
방금 PR을 만들었어. Linear 이슈에 PR 링크를 코멘트로 남기고 상태를 In Progress로 바꿔줘.
그리고 문제점(권한 이슈)을 'Blocker' 코멘트로 기록해줘.
이 방식의 문제는 대화를 통해 명시적으로 이슈트래커 동기화 지시를 해야만 한다는 점이다. 개발자는 매 변경점 마다 이슈를 갱신하기 위해 코딩 에이전트와 대화를 해야 한다.
문제점
- 작업 병목: 계획을 세우는 흐름과, Linear에 반영하는 흐름이 분리되어 있어 매 작업마다 “등록/업데이트” 지시가 요구된다.
- 누락 가능성: 깜박하고 작업 내역을 동기화하지 않는 등 인간의 실수 개입 여지가 있다.
- 일관성 부족: 코딩 에이전트와 대화를 통해 이슈 본문/제목/prefix 등을 기술하다 보면 일관성을 보장하기 어렵게 된다.
시도 2: CLAUDE.md 및 Sub-Agent 를 이용한 이슈 트래커 동기화 자동화
이번에는 매번 Linear 업데이트를 지시하는 대신, 계획 단계에서 정리한 내용을 자동으로 등록/업데이트하도록 CLAUDE.md에 규칙을 기술한다.
- CLAUDE.md: 구현 전에 반드시 이슈 트래커를 업데이트하도록 명시하는 규칙 문서
- Sub-Agent: 이슈 작성 형식과 예제를 프롬프트에 고정해, 항상 같은 템플릿으로 작성하게 하는 전담 에이전트
진행 흐름
1) CLAUDE.md에 동기화 규칙 명시: 구현에 들어가기 전에, 계획 내용을 이슈 트래커에 등록/업데이트하도록 규칙을 박아둔다.
2) Sub-Agent에 작성 형식 기술: 제목 규칙, 본문 섹션, 라벨/우선순위 등을 Sub-Agent 프롬프트로 템플릿 화한다.
3) 계획 수립: Claude Code와 대화로 스펙을 구체화하고 구현 계획을 체크리스트로 정리한다.
4) 구현: CLAUDE.md에 명시된 규칙에 따라 구현에 들어가기 전 이슈트래커에 계획과 진행사항을 갱신한다.
사용례
CLAUDE.md 예시
# CLAUDE.md
## Issue Tracker Sync
- 계획이 확정되면 항상 "구현 계획"을 체크리스트로 만든다.
- 구현을 시작하기 전에는 항상 구현 계획을 기반으로 Linear 이슈를 생성한다.
Sub-Agent 예시
[You are Issue Tracker Agent]
- Convert the current plan into a Linear issue update.
- Title rule: <PREFIX>: <verb> <object>
- Body sections: Background / Decisions / Alternatives / Checklist
- Default labels: agenticai, tooling
- Default priority: P2
문제점
- 누락:
CLAUDE.md에 규칙을 명시해도, 그 내용이 반드시 실행됨을 보장하지는 않는다. 대화 흐름이 길어지거나 컨텍스트가 여러 번 바뀌면,계획 → 구현전환 시점에서 동기화 스텝이 건너뛰어질 수 있다. - 진행사항 반영:
CLAUDE.md만으로는 구현 도중에 발생하는 모든 이력을 이슈 트래커에 반영하도록 제어하기 어렵다. 마찬가지로 누락이 발생한다. - 유연성 부족: 이미 논의된 이슈를 구현하거나, 존재하는 브랜치를 체크아웃 하는 등의 유연성을 워크플로우에 반영하기 어렵다.
Claude Code Hooks
위와 같이 특정 작업에 대해 반드시 실행을 보장해야 하는 경우, Claude Code의 Hooks 기능이 해결책이 될 수 있다.
Hook은 Claude Code의 특정 생명주기 이벤트에서 자동으로 실행되는 사용자 정의 셸 명령이다. 대화형으로 LLM에게 요청하거나 사전에 프롬프트로 기재하여 지시하는 방식과는 달리, Hook은 특정 상황에서 특정 동작을 강제할 수 있다.
다시 말해 Hook은 반드시 실행된다.
이벤트 발생 → Hook 트리거 → 스크립트 실행 → Exit Code에 따라 진행/차단
Hook은 다음과 같은 문제들을 해결할 수 있다.
1. 반복 작업 자동화: 파일 수정 후 진행사항 요약, 구현 전에 이슈 및 브랜치 생성 등
2. 프로젝트 규칙 강제: 특정 명령 차단, 파일 경로 검증, 네이밍 컨벤션 준수
3. 컨텍스트 자동 주입: 세션 시작 사전에 체크리스트 로드
예를 들어 PreToolUse 이벤트에 Write|Edit matcher를 설정하면 Claude가 파일을 수정하려 할 때마다 스크립트가 실행된다. 또한 PreCompact 이벤트를 활용하면 컨텍스트 윈도우가 압축되기 전에 현재까지의 작업 내용을 Linear 이슈에 코멘트로 남길 수 있다.
Claude Code Hook 이벤트 종류
| 이벤트 | 발생 시점 | matcher 지원 | 주요 용도 |
|---|---|---|---|
| UserPromptSubmit | 사용자 프롬프트 제출 직후, Claude 처리 전 | X | 프롬프트 검증, 컨텍스트 주입, 보안 필터링 |
| PreToolUse | 도구 파라미터 생성 후, 실행 전 | O | 특정 명령 차단, 민감 파일 보호, 입력 수정 |
| PermissionRequest | 권한 다이얼로그 표시 시 | O | 특정 도구 자동 승인/거부 |
| PostToolUse | 도구 실행 성공 직후 | O | 자동 포매팅, 로깅, 결과 검증 |
| Stop | 메인 에이전트 응답 완료 시 | X | 품질 게이트 (lint, test), 작업 완료 검증 |
| SubagentStop | 서브에이전트 작업 완료 시 | X | 서브태스크 완료 검증, 추가 작업 강제 |
| PreCompact | 컨텍스트 윈도우 압축 전 | X | 트랜스크립트 백업, 진행 상황 저장 |
| SessionStart | 세션 시작 또는 재개 시 | X | 개발 컨텍스트 로드, 환경 초기화 |
| SessionEnd | 세션 종료 시 | X | 정리 작업, 세션 통계 로깅 |
| Notification | Claude Code가 알림 전송 시 | O | 데스크톱 알림, 사운드 재생 |
이때 실행된 스크립트에서 반환하는 Exit Code에 따라 이후 진행을 제어할 수 있다.
예를 들어 main 브랜치에서 직접 파일을 수정하려는 시도를 감지하면 스크립트가 exit 2를 반환하고, stderr에 “main 브랜치에서는 직접 수정할 수 없습니다. Linear 이슈를 생성하고 feature 브랜치를 만드세요.”라는 메시지를 출력한다.
이 메시지는 Claude에게 전달되어, Claude가 스스로 Linear 이슈 생성 → 브랜치 생성 → 체크아웃 순서로 작업을 수정하게 된다.
Exit Code에 따른 흐름 제어
| Exit Code | 의미 | Claude에게 전달 | 동작 |
|---|---|---|---|
| 0 | 성공 | stdout (JSON) | 정상 진행. JSON 출력 시 decision 등 정교한 제어 가능 |
| 2 | 차단 에러 | stderr | 해당 동작 차단. stderr 내용이 Claude에게 자동 피드백되어 수정 유도 |
| 기타 | 비차단 에러 | X | stderr가 verbose mode에서만 표시. 실행은 계속됨 |
시도 3: Claude Code Hooks을 이용하여 누락 없이 원하는 동작을 일관성 있게 수행
앞서 살펴본 Hook의 특성을 활용하면 반드시 실행을 보장하여야 하는 Linear 워크플로우를 강제할 수 있다.
워크플로우는 다음과 같다.
1. 사용자 프롬프트 제출
└─ [UserPromptSubmit] check_linear_env.py → 환경 설정(Linear Team/Project 정보 등) 확인, 미설정 시 안내
2. Claude가 Plan Mode에서 구현 계획 수립
3. 구현 시도 (파일 수정)
└─ [PreToolUse: Write|Edit] ensure_linear_branch.py
├─ main 브랜치? → exit 2, "Linear 이슈를 생성하세요"
├─ 이슈 없음? → exit 2, "이슈를 먼저 생성하세요"
└─ 정상 브랜치 → exit 0, 진행
4. 구현 진행 중 컨텍스트 압축 필요
└─ [PreCompact] prompt → Linear 이슈에 진행 상황 코멘트
5. git commit 시도
└─ [PreToolUse: Bash] validate_commit_msg.py
├─ 형식 불일치? → exit 2, "feat(scope): description 형식을 사용하세요"
└─ 형식 일치 → exit 0, 커밋 진행
6. PR 생성 (Fixes ABC-123 포함) → 머지 시 Linear 이슈 자동 완료
다음과 같이 hooks.json 을 구성하면 Event/Matcher 별 스크립트를 실행할 수 있다. 물론 작업에 따라 스크립트 대신 프롬프트를 직접 기술할 수도 있다.
hooks.json 구성
{
"hooks": {
"UserPromptSubmit": [
{
"hooks": [
{
"type": "command",
"command": "python3 \"${CLAUDE_PLUGIN_ROOT}/scripts/check_linear_env.py\""
}
]
}
],
"PreToolUse": [
{
"matcher": "Write|Edit|ExitPlanMode",
"hooks": [
{ "type": "command", "command": "...check_linear_env.py" }
]
},
{
"matcher": "Write|Edit|ExitPlanMode",
"hooks": [
{ "type": "command", "command": "...ensure_linear_branch.py" }
]
},
{
"matcher": "Bash",
"hooks": [
{ "type": "command", "command": "...validate_commit_msg.py" }
]
}
],
"PreCompact": [
{
"hooks": [
{
"type": "prompt",
"prompt": "Pre-Compact: Sync progress to Linear..."
}
]
}
]
}
}
Hook-스크립트의 역할
| 스크립트 | 이벤트 | matcher | 역할 | Exit Code |
|---|---|---|---|---|
check_linear_env.py | UserPromptSubmit | – | 환경변수 설정 확인. 미설정 시 안내 메시지 출력 | 항상 0 (advisory) |
check_linear_env.py | PreToolUse | Write|Edit|ExitPlanMode | 파일 수정 전 환경 재확인 | 항상 0 (advisory) |
ensure_linear_branch.py | PreToolUse | Write|Edit|ExitPlanMode | Linear 이슈/브랜치 존재 확인. 없으면 생성 강제 | 2 (차단) |
validate_commit_msg.py | PreToolUse | Bash | git commit 시 Conventional Commits 형식 검증 | 2 (차단) |
| (prompt) | PreCompact | – | 컨텍스트 압축 전 Linear 이슈에 진행 상황 코멘트 | – |
Claude Code Plugin: 패키지 가능한 AI Tool Use Best Practice
Claude Code 의 Hook, Skill, MCP 설정을 패키징하는 방법을 살펴보자. Claude Code Plugin은 사용자가 구성한 Tool Use Best Practice를 재사용하고 공유할 수 있도록 제공되는 패키지이다.
Plugin 구조
Plugin은 다음과 같은 표준 디렉토리 구조를 따른다:
plugin-name/
├── .claude-plugin/
│ └── plugin.json # 플러그인 메타데이터 (필수)
├── hooks/
│ └── hooks.json # Hook 설정
├── scripts/ # Hook에서 실행할 스크립트
├── skills/ # Skill 정의 (SKILL.md)
├── agents/ # 특화된 에이전트 정의
├── commands/ # 슬래시 명령어
├── .mcp.json # MCP 서버 설정
└── README.md # 문서화
Marketplace로 배포하기
이러한 Plugin을 팀이나 커뮤니티와 공유하려면 Marketplace에 등록한다. Marketplace는 Plugin 카탈로그로, 사용자가 다양한 Plugin을 탐색, 설치, 관리할 수 있도록 한다.
참고 자료
Linear 이슈 트래커 – 코딩 에이전트 간의 워크플로우를 일관성 있게 유지하는 방법을 어떻게 Claude Code Plugin으로 작성하고 배포하는지에 대한 예제 프로젝트를 아래에 공개한다.
- Linear Workflow Plugin: https://github.com/bahamoth/claude-linear-workflow/
- Marketplace: https://github.com/bahamoth/claude-marketplace/
댓글 남기기