Slack 에러 스레드를 분석하여 Linear 티켓을 자동 생성하고, Claude Code로 버그 수정 Draft PR까지 만드는 시스템. 하네스 엔지니어링을 적용하여 AI 에이전트의 동작을 제어하고, 데이터를 보호하고, 코드 품질을 강제한다.
| 모듈 | 포트 | 역할 |
|---|---|---|
| webhook-server | 8080 | Slack/Linear 웹훅 수신, 스레드 분석, 티켓 생성 |
| worker | 8081 | 이슈 할당 시 Claude Code로 코드 분석/수정, Draft PR 생성 |
Slack 에러 스레드 → webhook-server (분석 + Linear 티켓 생성)
→ worker (Claude Code 실행 → Git push → Draft PR)
→ Slack/Linear 결과 회신
- Java 21, Spring Boot 3.5, Gradle
- PostgreSQL 16 (Docker Compose)
- Claude Code CLI
- Linear GraphQL API, Slack API, GitHub CLI
# PostgreSQL 컨테이너
docker compose up -d
# 애플리케이션
./gradlew :webhook-server:bootRun
./gradlew :worker:bootRun| 변수 | 설명 |
|---|---|
SLACK_BOT_TOKEN |
Slack Bot 토큰 |
SLACK_SIGNING_SECRET |
Slack 서명 검증 시크릿 |
LINEAR_API_KEY |
Linear API 키 |
GH_TOKEN |
GitHub 토큰 (PR 생성용) |
AI 에이전트가 안전하고 예측 가능한 방식으로 작동하도록 설계된 제어 구조. 3대 축: 제어(Control) / 감시(Monitoring) / 개선(Feedback)
SessionStart ────────────────────── 컨텍스트 주입 + harness-doctor 자동 진단 + 플랜 상태 초기화
▼
PreToolUse
├── guardrail-check.py ────────── 위험 명령 / 시크릿 / Bash 우회 차단
├── data-governance-check.py ──── 공통 규칙 + 역할별 테이블 접근 + LLM 유출 방지
▼
[도구 실행]
▼
PostToolUse
├── code-style-check.py ──────── 컨벤션 피드백 (즉시) + 5개+ 파일 시 code-reviewer 트리거
├── api-spec-update.py ───────── API 스펙 자동 갱신 (MD)
├── output-verify.py ─────────── Spotless 포매팅 + 컴파일 검증 (debounce 30s)
├── commit-message-validator.py ─ Conventional Commits 검증 + 타입-파일 일관성
├── feedback-loop.py ─────────── 실패 교훈 축적 → 다음 세션 주입
└── audit.py ─────────────────── JSONL 감사 로그
▼
Stop ── stop-final-check.py ────── 보안 감사 트리거 (최대 3회)
│ 테스트 생성 트리거 (소스 수정 + 테스트 미작성 시)
│ 의존성 검사 트리거 (build.gradle 수정 시)
│ 변경 검증 트리거 (Java 소스 3개+ 수정 시)
│ 성능 검사 트리거 (Service/Repository/Entity 수정 시)
│ 커버리지 게이트 트리거 (JaCoCo 80% 미달 시)
│ 데드 코드 탐지 트리거 (미사용 메서드 감지 시)
│ 빌드 검증
│ 세션 요약 생성 (.claude/session-logs/)
│ 검증 통과 시 트리거 상태 초기화
3-Layer 구조:
| Layer | 대상 | 적용 |
|---|---|---|
| 공통 규칙 | application-prod, PII 로깅 | 모든 역할 |
| 테이블 접근 | junior/senior/lead 테이블별 차등 | 역할별 |
| LLM 유출 방지 | 민감 쿼리, 컬럼, 파일 | 모든 역할 (lead 포함) |
역할 결정: git config user.email → access-policy.json 매핑 (미등록 = junior)
| 보호 수단 | 대상 |
|---|---|
settings.json deny |
하네스 파일 Edit/Write 차단 (hooks, governance, rules, CLAUDE.md) |
guardrail-check.py |
Bash로 보호 파일 읽기/복사 우회 차단 |
| SHA-256 체크섬 | harness-checksums.json + pre-push hook으로 수동 수정 탐지 |
| fail-closed | 보안 훅 에러 시 차단 (통과 아님) |
| 수단 | 역할 |
|---|---|
code-style-check.py |
@Autowired, System.out, var 등 컨벤션 피드백 (즉시) |
api-spec-update.py |
Controller/DTO 수정 시 docs/api-spec.md 자동 갱신 |
output-verify.py |
Spotless(palantir-java-format) 포매팅 + incremental compile (debounce 30s) |
commit-message-validator.py |
Conventional Commits 형식 검증 + 커밋 타입-파일 일관성 검사 |
stop-final-check.py |
세션 종료 전: 보안 감사 + 테스트 + 커버리지 + 데드 코드 + 빌드 검증 + 세션 요약 |
.claude/rules/*.md |
핵심 규칙 slim 포인터 (상세 템플릿은 .claude/references/에서 on-demand 로드) |
| 피드백 루프 | 실패 교훈 축적 → 다음 세션 주입 + 규칙 점진적 추가 |
# 전체 환경 자동 점검 + 설정 (권장)
/setup
# 또는 수동 설치
bash .claude/scripts/setup-hooks.sh # git pre-push hook 활성화
python3 .claude/scripts/update-checksums.py # 체크섬 갱신/setup 커맨드는 Java 21, Gradle, Docker, Git Hooks, 체크섬, 빌드를 한 번에 점검하고 자동 설정한다.
setup-hooks.sh를 실행하지 않으면 pre-push hook이 비활성 상태다. git은 기본적으로.git/hooks/를 보기 때문에,.claude/git-hooks/는 수동 설치가 필요하다.
.claude/
├── settings.json # 훅 파이프라인 + deny 권한
├── harness-checksums.json # SHA-256 체크섬 매니페스트
├── governance/
│ └── access-policy.json # 역할-테이블 매핑 + 멤버 이메일 + LLM 유출 정책
├── hooks/
│ ├── session-start.py # 컨텍스트 주입 + harness-doctor 자동 진단
│ ├── guardrail-check.py # 위험 명령 / 시크릿 / Bash 우회 차단
│ ├── data-governance-check.py # 공통 + 역할별 + LLM 유출 방지
│ ├── code-style-check.py # 컨벤션 피드백 + code-reviewer 트리거
│ ├── output-verify.py # Spotless 포매팅 + 컴파일 검증
│ ├── feedback-loop.py # 실패 교훈 축적
│ ├── audit.py # JSONL 감사 로그
│ ├── stop-final-check.py # 보안 감사 + 테스트 + 커버리지 + 데드 코드 + 빌드 + 세션 요약
│ ├── branch-protect-block.py # main 브랜치 직접 수정 차단
│ └── commit-message-validator.py # Conventional Commits 검증 + 타입-파일 일관성
├── git-hooks/
│ └── pre-push # 체크섬 무결성 검증
├── scripts/
│ ├── api-spec-update.py # API 스펙 자동 갱신 훅
│ ├── setup-hooks.sh # git hook 설치
│ └── update-checksums.py # 체크섬 갱신
├── agents/
│ ├── code-reviewer.md # 코드 리뷰 (5개+ 파일 수정 시 자동 트리거)
│ ├── change-validator.md # 변경 정합성 검증 (Stop에서 Java 3개+ 수정 시)
│ ├── performance-checker.md # 성능 안티패턴 탐지 (Stop에서 Service/Repo/Entity 수정 시)
│ ├── security-auditor.md # 보안 감사 (Stop에서 자동 트리거, 최대 3회)
│ ├── harness-doctor.md # 하네스 진단 (SessionStart 자동 실행)
│ ├── test-generator.md # 테스트 생성 (Stop에서 소스 수정 + 테스트 미작성 시)
│ ├── test-coverage-gate.md # JaCoCo 커버리지 검증 (Stop에서 80% 미달 시)
│ ├── dead-code-detector.md # 미사용 메서드/클래스 탐지 (Stop에서 자동)
│ └── dependency-checker.md # 의존성 검사 (Stop에서 build.gradle 수정 시)
├── references/ # 상세 컨벤션/템플릿 원본 (on-demand 로드)
│ ├── code-templates.md
│ ├── java-spring-conventions.md
│ ├── jpa-conventions.md
│ ├── database-schema.md
│ └── harness-guide.md
├── rules/ # slim 포인터 (항상 로드, references/로 연결)
│ ├── java-spring-conventions.md
│ ├── code-templates.md
│ ├── jpa-conventions.md
│ ├── database-schema.md
│ ├── design-principles.md
│ └── api-spec-guide.md
└── skills/ # 슬래시 커맨드 스킬
├── commit/ # /commit - Conventional Commits
├── openspec-propose/ # /opsx:propose
├── openspec-apply-change/ # /opsx:apply
├── openspec-explore/ # /opsx:explore
├── openspec-archive-change/ # /opsx:archive
└── audit-dashboard/ # /audit-dashboard — 감사 로그 시각화 + 드릴다운
.private/ # 런타임 상태 파일 (.gitignore 대상)
├── .edit-count # 세션 편집 카운터
├── .edited-files # 수정된 파일 목록
├── .learnings # 실패 교훈 (세션 간 유지)
├── .failing-tests # 빌드 실패 기록
├── .*-triggered # 에이전트 트리거 상태
└── audit/ # JSONL 감사 로그 + dashboard.html
.claude/session-logs/ # 세션 요약 로그 (.gitignore 대상)
└── {YYYY-MM-DD}.md # 날짜별 세션 요약 (변경 파일, 테스트, 에이전트, 커밋)
docs/
└── api-spec.md # API 스펙 (Markdown, 사람용)
openspec/ # OpenSpec 스펙 주도 개발
├── config.yaml # 프로젝트 컨텍스트 + 룰
├── specs/ # 메인 스펙 (source of truth)
└── changes/ # 변경 제안 + 아티팩트