{"id":49801188,"url":"https://github.com/karatuss/bstack","last_synced_at":"2026-05-12T14:06:55.274Z","repository":{"id":352566559,"uuid":"1200029468","full_name":"Karatuss/bstack","owner":"Karatuss","description":"Backend-specialized Claude Code harness for Java 21 / Spring Boot 3.x — 17 domain skills: architecture, JPA, security, testing, and more. | Java 백엔드 특화 Claude Code 하네스","archived":false,"fork":false,"pushed_at":"2026-04-20T06:26:59.000Z","size":61,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-20T08:12:03.433Z","etag":null,"topics":["ai-coding","anthropic","archunit","backend","claude","claude-code","developer-tools","harness","java","java21","jpa","llm-tools","spring-boot","spring-security","testcontainers"],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Karatuss.png","metadata":{"files":{"readme":"README.ko.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-03T00:53:04.000Z","updated_at":"2026-04-20T06:27:03.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Karatuss/bstack","commit_stats":null,"previous_names":["karatuss/bstack"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/Karatuss/bstack","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Karatuss%2Fbstack","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Karatuss%2Fbstack/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Karatuss%2Fbstack/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Karatuss%2Fbstack/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Karatuss","download_url":"https://codeload.github.com/Karatuss/bstack/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Karatuss%2Fbstack/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32942268,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-12T09:19:52.626Z","status":"ssl_error","status_checked_at":"2026-05-12T09:17:33.438Z","response_time":102,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-coding","anthropic","archunit","backend","claude","claude-code","developer-tools","harness","java","java21","jpa","llm-tools","spring-boot","spring-security","testcontainers"],"created_at":"2026-05-12T14:06:54.329Z","updated_at":"2026-05-12T14:06:55.270Z","avatar_url":"https://github.com/Karatuss.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# bstack\n\n\u003e Java 21 / Spring Boot 3.x 백엔드 특화 Claude Code 하네스\n\n[English](README.md)\n\n---\n\n## bstack란?\n\n**bstack**은 Java/Spring Boot 백엔드에 특화된 Claude Code 하네스입니다.\n[gstack](https://github.com/anthropics/gstack) 패턴을 백엔드 관점으로 재설계 — 트랜잭션 경계, 모듈 의존성, 쿼리 플랜, Spring Security filter chain에 특화.\n\n## 특징\n\n- **코드 수정 승인 워크플로우** — 수정 요청 시 계획 제시 → 사용자 승인 → 구현 순서 강제\n- **17개 도메인 스킬** — architect, persistence, security, test 등 백엔드 고유 복잡도를 각 skill로 분리\n- **CLAUDE.md 템플릿** — 200줄 이하 유지, 기본 원칙 + 라우팅 + 아키텍처 제약 + docs/ 포인터\n- **ArchUnit 연동** — 레이어 제약을 코드로 강제, 위반 시 에러 메시지에 수정 방법 내장\n- **Context Rot 방지** — 테스트 성공은 한 줄, 실패만 상세 출력\n- **세션 간 상태 추적** — `docs/progress/claude-progress.json` (Markdown보다 안전한 JSON)\n- **전역/프로젝트 양방향 설치** — symlink(개발 중 즉시 반영) 또는 vendor(팀 공유)\n\n## 구조\n\n```\nbstack/\n├── SKILL.md                          # 진입점 \u0026 스킬 라우팅 테이블\n├── CLAUDE.md                         # 하네스 README\n├── setup                             # 설치 스크립트\n│\n├── skills/\n│   ├── brainstorming/SKILL.md        # 새 기능 아이디어, 접근법 탐색\n│   ├── architect/SKILL.md            # DDD, 모듈 경계, 레이어 설계\n│   ├── spec/SKILL.md                 # 스펙 문서, ADR 작성\n│   ├── writing-plans/SKILL.md        # 스펙 → TDD 실행 계획\n│   ├── subagent-driven/SKILL.md      # 계획 파일 분산 실행\n│   ├── conventions/SKILL.md          # 구현 전 컨벤션 확인\n│   ├── spring-core/SKILL.md          # Bean, 프로파일, 자동구성\n│   ├── persistence/SKILL.md          # JPA, N+1 탐지, 트랜잭션 경계\n│   ├── api-review/SKILL.md           # REST 계약, 에러 포맷, 버저닝\n│   ├── security/SKILL.md             # Spring Security, JWT, OAuth2\n│   ├── test/SKILL.md                 # TestContainers, Mockito, 커버리지\n│   ├── perf/SKILL.md                 # N+1, HikariCP, 비동기 smell\n│   ├── audit/SKILL.md                # 보안 + 동시성 통합 감사\n│   ├── arch-guard/SKILL.md           # ArchUnit 제약 코드화\n│   ├── investigate/SKILL.md          # 버그 탐색 (스코프 freeze 원칙)\n│   ├── writing-skills/SKILL.md       # failure-log → SKILL.md 업데이트\n│   └── ship/SKILL.md                 # PR 체크리스트, 릴리즈 gate\n│\n├── templates/\n│   └── CLAUDE.md.template            # 프로젝트 CLAUDE.md 시작점\n│\n└── docs/\n    ├── ARCHITECTURE.md               # 레이어 구조, 기술 스택\n    ├── LAYER_RULES.md                # 의존성 규칙 상세 + ArchUnit 연결\n    ├── RED_FLAGS.md                  # CRITICAL/HIGH/MEDIUM/LOW 함정 목록\n    ├── specs/                        # 기능 스펙, ADR 보관\n    ├── plans/                        # TDD 실행 계획 파일\n    ├── lessons/\n    │   ├── LESSONS_LEARNED.md        # 반복 패턴 학습 기록\n    │   └── failure-log.json          # 버그 탐색 실패 원인 누적\n    └── progress/\n        └── claude-progress.json.template  # 장기 작업 세션 간 상태 추적\n```\n\n## 스킬 라우팅\n\n### 탐색 / 계획\n\n| 요청 유형 | 스킬 |\n|---|---|\n| 새 기능 아이디어, 접근법 탐색 | `/brainstorming` |\n| 기존 코드 레이어/모듈 경계 검토 | `/architect` |\n| 스펙 / ADR 문서화 | `/spec` |\n| 스펙 → TDD 실행 계획 | `/writing-plans` |\n| 계획 분산 실행 (서브에이전트) | `/subagent-driven` |\n\n### 도메인\n\n| 요청 유형 | 스킬 |\n|---|---|\n| 구현 전 컨벤션 확인 | `/conventions` |\n| Spring Boot 패턴 / 설정 | `/spring-core` |\n| JPA / 트랜잭션 / 쿼리 | `/persistence` |\n| REST API 설계 검토 | `/api-review` |\n| 보안 / 인증 / 인가 | `/security` |\n| 테스트 작성 / 전략 | `/test` |\n| 성능 / N+1 / 비동기 | `/perf` |\n| 보안+동시성 통합 감사 | `/audit` |\n| ArchUnit / 레이어 위반 | `/arch-guard` |\n\n### 실패 / 피드백\n\n| 요청 유형 | 스킬 |\n|---|---|\n| \"왜 안 되지\" 버그 탐색 | `/investigate` |\n| failure-log → SKILL.md 업데이트 | `/writing-skills` |\n\n### 완료\n\n| 요청 유형 | 스킬 |\n|---|---|\n| PR / 배포 전 검토 | `/ship` |\n\n## 설치\n\n### 전역 설치 (모든 프로젝트에서 사용)\n\n```bash\ngit clone https://github.com/Karatuss/bstack.git ~/works/bstack\ncd ~/works/bstack \u0026\u0026 ./setup\n# ~/.claude/skills/bstack 심볼릭링크 생성\n# ~/.claude/skills/{architect,persistence,...} 개별 링크 생성\n```\n\n또는 `~/.claude/skills/`에 직접 클론:\n\n```bash\ngit clone https://github.com/Karatuss/bstack.git ~/.claude/skills/bstack\ncd ~/.claude/skills/bstack \u0026\u0026 ./setup\n```\n\n### 프로젝트 적용\n\n**Symlink 방식** (개발 중 변경 즉시 반영):\n\n```bash\ncd your-spring-project\nmkdir -p .claude/skills\nln -s ~/.claude/skills/bstack .claude/skills/bstack\ncp ~/.claude/skills/bstack/templates/CLAUDE.md.template ./CLAUDE.md\n# 프로젝트명, 스택, 모듈 구조에 맞게 편집\n```\n\n**Vendor 방식** (팀 공유, 버전 고정):\n\n```bash\ncd ~/.claude/skills/bstack \u0026\u0026 ./setup --project=/path/to/your-project\n# .claude/skills/bstack/ 에 복사 + git 히스토리 제거\n# CLAUDE.md 없으면 템플릿 자동 생성\n```\n\n### 업데이트\n\n```bash\ncd ~/works/bstack \u0026\u0026 git pull origin main\n# symlink 방식이면 자동 반영. vendor 방식이면 ./setup --project=... 재실행.\n```\n\n## 사용법\n\nClaude Code 세션에서:\n\n```\n/bstack           — 하네스 진입, 스킬 라우팅 안내\n/brainstorming    — 새 기능 설계 탐색 (코드 없을 때)\n/architect        — 레이어 설계, DDD, 모듈 경계 검토\n/spec             — 스펙 문서, ADR 작성\n/writing-plans    — 스펙 → TDD 실행 계획 생성\n/subagent-driven  — 계획 파일 서브에이전트 분산 실행\n/conventions      — 구현 전 컨벤션 확인\n/spring-core      — Spring Boot 관용 패턴, 설정\n/persistence      — JPA N+1 탐지, 트랜잭션 경계 설계\n/api-review       — REST API 계약, 에러 포맷, 버저닝\n/security         — Spring Security, JWT, RBAC 구현\n/test             — TestContainers 설정, 커버리지 전략\n/perf             — 쿼리 성능, HikariCP, 비동기 smell\n/audit            — 보안 + 동시성 통합 감사\n/arch-guard       — ArchUnit 레이어 제약 코드화\n/investigate      — 버그 원인 분석 (스코프 freeze 후 탐색)\n/writing-skills   — failure-log 반영 → SKILL.md 개선\n/ship             — PR 머지 전 체크리스트\n```\n\n## CLAUDE.md 구조\n\n프로젝트 루트의 `CLAUDE.md`는 **200줄 이하**로 유지. 세 가지만 포함:\n\n```\n1. 프로젝트 컨텍스트     — 스택, 빌드 명령, 모듈 구조\n2. 아키텍처 제약         — 레이어 의존성 규칙, 금지 패턴\n3. 스킬 라우팅 테이블    — 요청 유형 → 스킬 매핑\n```\n\n세부 규칙은 모두 `docs/`와 `skills/`로 위임.\n`templates/CLAUDE.md.template`을 시작점으로 사용.\n\n## 아키텍처 원칙\n\n의존성 방향 (단방향):\n\n```\nPresentation → Application → Domain\nInfrastructure → Domain (Repository 인터페이스 구현)\n```\n\n**절대 금지** (ArchUnit으로 CI 강제):\n- Controller에서 Repository 직접 접근\n- Entity를 API Response로 직접 노출\n- `@Transactional`을 Controller에 선언\n- Domain 레이어가 `org.springframework.*`에 의존\n- 패키지 간 순환 의존\n\n## RED FLAGS 요약\n\n| 심각도 | 예시 |\n|---|---|\n| 🔴 CRITICAL | 하드코딩된 JWT secret, SQL Injection 가능 코드 |\n| 🟠 HIGH | N+1 쿼리, Entity 직접 반환, 재고 동시성 미처리 |\n| 🟡 MEDIUM | `readOnly=true` 미사용, TestContainers 대신 Mock DB |\n| 🔵 LOW | `@Autowired` 필드 주입, 테스트 SQL 로그 과다 |\n\n전체 목록: [`docs/RED_FLAGS.md`](docs/RED_FLAGS.md)\n\n## 관련 레퍼런스\n\n### 하네스 패턴\n- [gstack](https://github.com/anthropics/gstack) — Claude Code 하네스 원형 (frontend + SDLC 기반)\n- [Claude Code Docs — Skills](https://docs.anthropic.com/ko/docs/claude-code/skills) — skills 공식 문서\n\n### Java/Spring 특화 레퍼런스\n- [decebals/claude-code-java](https://github.com/decebals/claude-code-java) — Java 특화 하네스, 18개 재사용 가능한 skills\n- [Jeffallan/claude-skills](https://github.com/Jeffallan/claude-skills) — Spring Boot 3.x, Java 21, WebFlux, TestContainers 커버\n- [jdubois/dr-jskill](https://github.com/jdubois/dr-jskill) — Spring Boot core, persistence-jpa 특화\n\n### 설계 원칙\n- [HumanLayer — Claude Code 실전 교훈](https://wikidocs.net/blog/@jaehong/9481/) — Context Rot 방지, 세션 간 상태 추적 패턴\n- [OpenAI Harness Engineering](https://openai.com/ko-KR/index/harness-engineering/) — AGENTS.md를 백과사전으로 쓰면 안 되는 이유, 구조화된 docs/ 운영 방법\n- [ArchUnit](https://www.archunit.org/) — 아키텍처 제약을 테스트 코드로 강제\n\n## 요구 사항\n\n- [Claude Code](https://docs.anthropic.com/ko/docs/claude-code) CLI 설치\n- Java 21+\n- Spring Boot 3.x\n- Maven (`./mvnw`) 또는 Gradle (`./gradlew`)\n\n## 라이선스\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkaratuss%2Fbstack","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkaratuss%2Fbstack","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkaratuss%2Fbstack/lists"}