akinalpfdn/claude-ground

Claude Code를 위한 최소한의 규칙 시스템입니다. 단계 추적 (phase tracking), 결정 로그 (decision logging), 정직한 반박 (honest pushback), 디버그 규율 (debug discipline), 언어별 모범 사례 (language-specific best practices), 그리고 재사용 가능한 기술 (reusable skills)을 통해 Claude에게 기본적으로 부족한 구조적 규율을 부여합니다.

Claude Code는 유능합니다. 하지만 기본 설정 상태로 내버려 두면 다음과 같은 경향을 보입니다:

• 구현 중간에 원래 계획을 놓침
• 막혔을 때 묻지 않고 조용히 단순화하거나 방향을 전환함
• 반박해야 할 상황에서 사용자의 의견에 동조함
• 멈춰서 생각하는 대신 실패한 동일한 방식을 무차별적으로 시도함 (Brute-force)
• 기존 코드를 먼저 이해하지 않고 수정함
• 테스트를 건너뛰거나 피상적인 테스트를 작성함
• 인라인 스타일 (inline styles), 하드코딩된 색상 (hardcoded colors), 그리고 일반적인 AI 미학 (generic AI aesthetics)을 사용함

이것들은 모델의 실패가 아니라, 명시적인 규칙 없이는 도전받지 않는 기본 설정값들입니다.

** rules/common/** — 모든 프로젝트에서 항상 활성화됨:

규칙 파일	역할
core.md	단계 관리 (Phase management), 승인 게이트 (approval gates), 정직한 반대 (honest opposition), 시간 추정 (time estimates), 주기적 분석 (periodic analysis)
decisions.md	결정 로그 (Decision log) 형식 및 규칙
git.md	브랜치 전략 (Branch strategy), 컨벤셔널 커밋 (conventional commits), 커밋 규율 (commit discipline), 버전 관리 (versioning)
testing.md	테스트 시점, 명명 규칙 (naming), 구조, 모킹 (mocks) 대 통합 테스트 (integration), 커버리지 (coverage)
debug.md	2회 시도 규칙 (Two-attempt rule), 구조적 분석 (structured analysis), 오류 은폐 금지 (no error masking)
existing-code.md	수정 전 읽기, 기존 패턴 준수, 리팩토링 (refactoring)과 기능 구현 (features) 분리
frontend.md	테마 우선 (Theme-first), 인라인 스타일 금지, 의도적인 디자인 (UI 프로젝트 전용)
security.md	입력 검증 (Input validation), 인증 (auth), 비밀값 (secrets), 헤더 (headers), 속도 제한 (rate limiting) 필수 사항 (프로덕션)
deploy.md	서버 강화 (Server hardening), TLS, systemd, 모니터링 필수 사항 (프로덕션)
observability.md	구조적 로깅 (Structured logging), 상태 확인 (health checks), 외부 모니터링 필수 사항 (프로덕션)
oss-hygiene.md	브랜치 보호 (Branch protection), 태그 불변성 (tag immutability), 서명 (signing), 거버넌스 (open source)

** rules/[language]/** — 언어별 모범 사례 (Language-specific best practices):

언어	주요 규칙
Go	Goroutine 생명주기 (lifecycle), 에러 래핑 (error wrapping), 인터페이스 설계 (interface design), 패키지 구조 (package structure), 테이블 기반 테스트 (table-driven tests)
...

** commands/** — 재사용 가능한 기술 (slash commands):

기술 (Skill)	기능
cg-mac-release	전문적인 DMG와 함께 macOS 앱을 빌드, 서명, 공증(notarize)하고 GitHub release로 게시
cg-devplan	Claude Code가 따를 수 있도록 구조화된 개발 계획 생성
cg-store-listing	ASO(App Store Optimization)가 최적화된 App Store / Google Play 등록 메타데이터 생성
cg-security-hardening	완전한 보안 강화 가이드 — OWASP 준수, 다중 언어 지원, 검증 테스트 포함
cg-indie-deploy	단일 VPS에 배포 — Caddy/nginx, systemd, TLS, 백업, 롤백
cg-indie-observability	구조화된 로깅 (structured logging), 에러 트래킹 (error tracking), 업타임 모니터링 (uptime monitoring), 알림 (alerting)
cg-oss-git-hygiene	OSS 리포지토리 설정 — 규칙 세트 (rulesets), 서명 (signing), 템플릿 (templates), Dependabot, 분류 (triage)

모든 규칙은 MUST / SHOULD / RECOMMENDED 심각도 수준을 사용하여, Claude가 무엇이 엄격한 규칙이고 무엇이 모범 사례인지 알 수 있도록 합니다.

** templates/** — 새 프로젝트를 위한 시작점:

CLAUDE.md
— 프로젝트 컨텍스트 파일. 기술 스택 (tech stack), 아키텍처 (architecture), 활성 규칙 (active rules).

DECISIONS.md
— 채워 넣을 준비가 된 빈 결정 로그 (decisions log).

phases/PHASE-01.md
— 첫 번째 단계 템플릿.

세 가지 요소가 설치되며, 각각 다른 위치로 들어갑니다:

항목	위치	효과
규칙 (Rules)	~/.claude/rules/ (전역/global)	모든 프로젝트, 모든 세션에서 활성화
기술 (Skills)	~/.claude/commands/ (전역/global)	어디서든 사용 가능한 슬래시 명령어 (slash commands)
템플릿 (Templates)	현재 작업 디렉토리 (Current working directory)	하나의 프로젝트를 위한 CLAUDE.md, DECISIONS.md, phases/

규칙과 기술은 항상 전역(global)입니다. 템플릿은 항상 명령어를 실행하는 디렉토리에 로컬(local)로 적용됩니다.

npm install -g claude-ground

의존성 없음 — Node.js 내장 기능만 사용합니다.

claudeground # 대화형 (interactive) — 언어 + 기술 선택
claudeground install go typescript # 비대화형 (non-interactive) — 언어를 직접 지정

이 과정은 공통 규칙 (common rules)과 선택한 언어 규칙을 ~/.claude/rules/에 설치하고,

선택한 기술 (skills)을 ~/.claude/commands/에 설치합니다.

한 번만 수행하면 어디에서나 작동합니다.

프로젝트 디렉토리에서 다음을 실행하세요:

cd your-project
claudeground init # 대화형 (interactive) — 언어, 기술, UI 선택
claudeground init go swift # 비대화형 (non-interactive) — 특정 언어 지정

이 명령은 프로젝트에 UI가 있는지(프론트엔드 규칙을 활성화하기 위해)를 묻고, 다음을 생성합니다:

your-project/
├── CLAUDE.md ← 이 파일을 채우세요
├── DECISIONS.md ← 첫 번째 스택 결정을 기록하세요
...

CLAUDE.md를 열고 다음 내용을 작성하세요:

• 프로젝트가 수행하는 작업
• 기술 스택 (tech stack) 및 선정 이유
• 적용되는 언어 규칙의 주석 해제
• Claude를 위한 프로젝트별 제약 사항

패키지를 업데이트할 때 (npm update -g claude-ground), 규칙과 기술을 다시 적용하세요:

claudeground update # 저장된 설정을 사용하여 재설치

언어 및 기술 선택 사항은 첫 설치 시 ~/.claude/.eclaude-ground.json에 저장되므로, 매번 다시 선택할 필요가 없습니다.

긴 구현 작업은 컨텍스트 리셋 (context resets) 상황에서도 유지될 수 있도록 단계별 파일 (phase files)을 사용합니다:

.claude/phases/
├── PHASE-01-done.md ← 완료됨
├── PHASE-02-done.md ← 완료됨
...

각 단계 파일에는 목표 (goal), 작업 목록 (task list), 수락 기준 (acceptance criteria)이 포함됩니다. 코드 스니펫 (code snippets)은 포함하지 않습니다. 단계는 구현이 아닌 목표입니다.

Claude는 작업을 계속하기 전에 활성화된 단계 파일을 확인합니다. 사용자의 승인 없이는 다음 단계를 시작하지 않습니다.

claude-ground/
├── cli.js
├── package.json
...

규칙 (Rules)은 다음과 같아야 합니다:

• 단순히 Claude에게 좋은 관행을 상기시키는 수준이 아니라, 동작을 변경할 수 있을 만큼 충분히 구체적이어야 함
• 언어 관용적 (Language-idiomatic) — 해당 생태계를 잘 아는 사람의 관점에서 작성됨
• Claude가 어차피 작성할 코드 스니펫을 포함하지 않음
• 심각도 (severity) 태그를 지정해야 함:
  MUST(강제 규칙), SHOULD(권장 사항), RECOMMENDED(선택 사항)

기술 (Skills)은 다음과 같아야 합니다:

• 범용적 (Generic) — 사용자 특정 값을 하드코딩하지 말고 플레이스홀더 (placeholders)를 사용함
• 독립적 (Self-contained) — commands/ 내의 기술당 하나의 .md 파일 사용
• 프로덕션 중심 (Production-focused) — 데모가 아닌 실제 워크플로 (workflows) 반영

새로운 언어 규칙, 기술, 수정 사항 및 개선 사항을 언제든 환영합니다.