ttutak 뚝딱

개요

ttutak은 Claude Code 위에서 동작하는 개발 자동화 플러그인입니다. 9개 스킬, 9개 에이전트가 협업하여 자연어 요청 하나로 전체 개발 사이클을 수행합니다.

안전장치

9개 스킬

setup — 초기 설정

플러그인 설치 후 최초 1회 실행합니다. 필수 도구(gh CLI)와 GitHub 인증을 확인하고, Slack 웹훅을 연동합니다.

/ttutak:setup

설정 항목

context — 도메인 지식 관리

기획서, 요구사항 문서, 코드베이스를 분석하여 도메인 지식을 등록합니다.

5가지 모드 자동 판단

생성되는 문서 구조

context/{도메인}/
├── README.md          ← 도메인 개요 (배경, 문제, 사용자, 성공기준, 담당자)
├── PROJECTS.md        ← 관련 GHE 레포 매핑
├── glossary.md        ← 도메인 용어 사전
├── architecture.md    ← 전체 구조 요약 + 주제 문서 링크
├── status.md          ← 구현 추적 (AC별 ✅/⬜)
└── {주제}/README.md   ← 주제별 상세 정책/설계

답변 품질 게이트

context는 모호한 답변을 허용하지 않습니다. "많다", "자주" 대신 정량 수치를 요구하고, "효율화", "개선" 같은 추상어가 나오면 구체화를 요청합니다. 그래도 모르는 항목은 ❓로 남기고 진행합니다.

dev — 전체 개발 파이프라인

자연어 요청 하나로 PRD 작성부터 PR 생성까지 전체 사이클을 수행합니다. 자연어를 분석하여 모드를 자동 결정합니다.

자연어 의도 파싱

7단계 파이프라인

정상 경로 (Normal)

긴급 경로 (Hotfix)

각 Phase 상세

Phase 1: Setup

1. 진행 중 작업 감지 (.dev/state.md) — 이전 작업 있으면 재개 여부 확인
2. Git 저장소 확인
3. 베이스 브랜치 결정 + 동기화 (git pull)
4. 프로젝트 정보 수집 (5개 작업 병렬)
   • 프로젝트 타입 감지 (build.gradle.kts → java-spring 등)
   • 디렉토리 구조 수집
   • CLAUDE.md 컨벤션 확보
   • 도메인 컨텍스트 매칭 (context/*/PROJECTS.md)
   • 외부 규격 참조 탐색 (references/ → REFERENCES 변수)
5. 관련 코드 맵 생성 — 키워드 추출 → Grep → 핵심 파일 15개 이내
6. 작업 브랜치 생성 + .gitignore 보강 + 상태 초기화

Phase 2: Requirements — PRD Q&A

1. product-owner 에이전트 호출 (PRD 작성)
2. PRD 전문 표시 + 3관점 품질 자가 검증
   • 유저 경험 검증: 사용자가 자연스럽게 이해하고 행동할 수 있는가
   • 해석 여지 제거: "크게", "적절히" 대신 구체적 수치가 있는가
   • 엣지케이스 커버리지: 빈 상태, 로딩, 에러, 최솟값/최댓값
3. 질문 → AskUserQuestion 변환 → 답변 반영 — 최대 1회
4. 사용자 승인 (승인 / 수정 요청) → .dev/prd.md 저장

Phase 3: Design — 설계 Q&A

1. architect 에이전트 호출 (기술 설계)
2. 설계 초안 전문 표시
3. 설계 비판 검토 (중형/대형만)
   • design-critic이 암묵적 가정 도전, 과잉 설계 식별
   • MUST-ADDRESS → architect 설계 수정
   • CONSIDER → 참고 사항으로 기록
4. 사용자 승인 (최대 2회 반복) → .dev/design.md 저장

Phase 4: Implement — 구현 + 자기점검

1. 구현 계획 제시 (변경 파일, 유형, 배치 테이블) → 사용자 승인
2. 의존성 분석 → 배치 구성
   • 파일 배타적 잠금: 같은 파일을 수정하는 단계는 같은 배치에 넣지 않음
   • import/참조 의존: 신규 타입을 참조하면 순차 배치
   • 위상 정렬로 B1 → B2 → B3 배치 배정
3. 배치별 coder 디스패치 (병렬 실행)
   • 단일 배치+단일 단계: 기존 전체 모드 coder 호출
   • 배치 내 2개 이상: 동시 coder Task 발행 (각 coder는 담당 파일만 수정)
   • 배치 간 통합 빌드 검증 → 실패 시 원인 coder 특정 후 수정 재호출
4. 자기점검 (qa-manager)
   • Critical → coder 자동 수정 (1회)
   • Warning/Info → phase-review로 이월
   • QUESTION → phase-review로 이월

Phase 5: Review — QA + 보안 감사

1. Mechanical Gate
   • 빌드 실패 → coder 자동 수정 → 1회 재시도
   • 테스트 실패 → coder 자동 수정 → 1회 재시도
2. qa-manager + security-auditor 병렬 호출
   • QA: 코드 리뷰 + 스펙 충족 검증
   • 종합 검증: PRD + 설계서 + diff 교차 검증
3. 결과 합산 → Trust Ledger 생성 → Critical 자동 수정 — 최대 2회

Phase 6: Complete

1. 인수 검증 (product-owner) — PRD 수용 기준 대비 검증
2. /commit 스킬 실행 — 빌드 체크 + 한국어 커밋
3. /pull-request 스킬 실행 — PR 본문 + Trust Ledger 요약
4. 도메인 status.md 갱신 + context 환류 제안

정체 감지 + 에스컬레이션

구현/리뷰 단계에서 진전이 없으면 자동으로 전문 에이전트에게 에스컬레이션합니다.

상태 저장과 재개

.dev/state.md에 현재 진행 상태를 기록합니다. "이어서 해줘"라고 말하면 중단된 Phase의 중단된 Step부터 정확히 재개합니다. 배치 실행 중 중단되면 완료된 배치는 건너뛰고 다음 배치부터 재개합니다.

# .dev/state.md 예시
phase: implement
status: in_progress
branch: JIRA-123
base: main
current-step: "coder 구현 (B2)"
phases:
  setup: completed
  requirements: completed
  design: completed
  implement: in_progress
steps:
  implement:
    - 구현 계획 승인: completed
    - 배치 구성: completed
    - coder 구현 (B1, 2단계 병렬): completed
    - 빌드 검증 (B1): completed
    - coder 구현 (B2, 1단계): in_progress

9개 에이전트 팀

dev 스킬의 핵심은 역할이 분리된 에이전트 팀이 협업하는 구조입니다.

모델 라우팅 원칙

모든 에이전트가 같은 모델을 쓰지 않습니다. 작업 특성에 따라 모델을 배정합니다.

컨텍스트 슬라이싱

에이전트에게 모든 정보를 전달하면 토큰 낭비입니다. 역할별로 필요한 섹션만 슬라이싱합니다.

references/ — 외부 규격 참조

프로젝트가 준수해야 할 외부 규격/표준(시큐어코딩 가이드, API 설계 표준, eGovFrame 규칙 등)을 references/ 디렉토리에 넣어두면 dev 파이프라인이 자동으로 참조합니다.

사용법

# 프로젝트 루트에 references/ 디렉토리 생성 후 규격 문서 배치
references/
├── 시큐어코딩-가이드.md
├── API-설계-표준.md
└── eGovFrame/
    └── 규칙.md

파이프라인 연동

핵심 설계

권장 작성 팁

기존 문서를 그대로 넣어도 동작합니다. 아래 팁을 따르면 에이전트가 더 효과적으로 참조합니다.

lens — 비즈니스 정책 탐지

코드에서 비즈니스 정책을 찾아 PO/PD가 읽을 수 있는 보고서로 출력합니다. 읽기 전용 — 코드를 수정하지 않습니다.

페르소나: 기술 번역자

코드를 읽되, 출력은 비즈니스 언어로 번역합니다.
PurchaseLimitPolicy → "구매 한도 정책 (PurchaseLimitPolicy)"
코드 변경을 제안하지 않습니다. 확인이 필요한 사항만 안내합니다.

5단계 Phase

1. Prepare — 쿼리 키워드 추출 → 프로젝트 확정
2. Explore: Agent(Explore)로 코드에서 정책 구현 발견
   • 1단계: 후보 수집 (Glob + Grep, Read 없이)
   • 2단계: 입구 추적 (Controller/Handler Read)
   • 3단계: 핵심 파일 정독 (Service/Policy/Rule Read)
3. Report — "대상에게 무슨 일이 일어나는가" 관점으로 합성
4. (선택) Impact — architect + security-auditor 병렬 분석
5. (선택) Impact-Report — PO 친화적 영향도 보고서

research — 도메인 리서치

웹 검색과 문서 분석을 병행하여 출처가 명확한 조사 결과를 산출합니다. /context --from으로 결과를 context 문서에 반영할 수 있습니다.

3가지 결과물 형태

4단계 워크플로우

1. 인터뷰 — 주제, 결과물 형태, 조사 깊이를 확인 (인자로 지정 시 스킵)
2. 검색 실행 — 키워드 도출 → WebSearch → URL 선별 → WebFetch로 내용 수집
3. 검증 + 보강 — 목표 충족, 완성도, 정확성, 균형 4기준 자기검증. 부족 시 1회 보강
4. 결과물 생성 — 선택한 형태로 .research/에 저장

조사 깊이

context 연동

/research 결제 시스템 트렌드
→ .research/결제-시스템-트렌드-20260316.md 생성

/context 결제 --from .research/결제-시스템-트렌드-20260316.md
→ context/결제/ 문서에 리서치 결과 반영

수칙

humanizer — AI 글쓰기 교정

AI가 생성한 텍스트에서 40+가지 패턴을 감지하고 교정합니다. Wikipedia의 "Signs of AI writing" 가이드와 한국어 AI 글쓰기 패턴 연구를 기반으로 합니다.

두 가지 모드

심각도 분류

40+ 감지 패턴

한국어 P1 — 즉시 수정

한국어 P2 — 맥락 판단

영어 P1 — 즉시 수정

공통 패턴

콘텐츠 유형별 적용

교정 예시

ttutak 소스코드를 기반으로 "시스템 구성 설명서"를 AI가 작성했을 때의 교정 전/후 비교입니다.

Before — AI 초안

감지 결과: P1 18건 P2 9건 P3 5건 — 총 32건

감지 리포트 (주요 항목)

After — humanizer 교정

핵심 차이

test — 테스트 자동 작성

도메인별로 단위/통합/E2E 테스트를 자동 작성합니다. 기존 테스트의 구조와 코딩 스타일을 분석하여 동일한 패턴으로 생성하며, 커버리지 목표를 검증합니다.

사용 예시

"테스트 작성해줘"                              ← 변경 코드 기반 자동 감지
"appointment 도메인 테스트 추가해줘"             ← 특정 도메인 지정
"단위 테스트만 작성해줘 --type unit"             ← 유형 선택
"커버리지 90% 목표로 테스트해줘 --coverage 90"   ← 커버리지 목표

테스트 유형별 생성 위치 (예시)

실행 흐름

1. 환경 감지 — 프로젝트 타입, 테스트 프레임워크, 기존 테스트 구조/스타일 분석
2. 대상 도메인 결정 — dev 컨텍스트(PRD/AC) 또는 변경 파일 기반 자동 감지
3. 테스트 계획 수립 — 기존 커버리지 분석 → 누락 테스트 도출 → 사용자 승인
4. 테스트 작성 — 단위 → 통합 → E2E 순서로 coder 에이전트가 작성
5. 실행 및 검증 — 테스트 실행 + 실패 시 자동 수정(1회) + 커버리지 확인

dev 파이프라인에서는 커밋 전에 자동 호출됩니다. hotfix 모드에서는 건너뜁니다.

commit / pull-request

commit — 커밋 자동화

1. 사전 확인 — Git 저장소 + 변경사항 + 빌드 실행
2. 타입 파싱 — 브랜치명에서 추출 (feat/login → feat)
3. 커밋 메시지 생성 — {type}: 한국어 요약 (50자 이내) + 본문
4. 커밋 실행
   • 빌드 아티팩트 tracking 해제 (build/, node_modules/)
   • 민감 파일 감지 (.env, *.key, *.pem, credentials*, *secret*) → 경고
   • 20개 초과 변경 → 전체 스테이징 확인
   • HEREDOC 포맷으로 커밋
5. context 동기화 체크

pull-request — PR 자동화

1. 사전 확인 — gh CLI + 인증 + origin remote + 베이스 브랜치
2. 타입 매핑 — feat→FEATURE, fix→BUGFIX, docs→DOCS ...
3. PR 제목 — [{TYPE}] 서술형 한국어 문장 (50자 이내)
4. PR 본문 (문장형 서술)
   • Background: 왜 이 변경이 필요한가
   • Summary: 무엇을 했는가
   • Changes: 기능 단위로 무엇이 바뀌었는가
   • Checklist: 변경 내용에 따라 동적 생성
5. PR 생성 + Slack 알림