wednesday-solutions/ai-agent-skills

Wednesday Solutions 프로젝트를 위한 AI 기술(skills) — git 규율(discipline), PR 자동화, 터미널 대시보드, 그린필드(greenfield) 계획, 그리고 실시간 채팅, 드리프트 탐지(drift detection), 테스트 생성 기능을 갖춘 브라운필드(brownfield) 코드베이스 인텔리전스.

• Node.js ≥ 18
• npm ≥ 8

옵션 1 — npx (설정 불필요)

npx @wednesday-solutions-eng/ai-agent-skills install

옵션 2 — global (전역 설치)

npm install -g @wednesday-solutions-eng/ai-agent-skills
wednesday-skills install

옵션 3 — shell (npm 미사용)

bash install.sh

프로젝트 루트에서 실행하세요. 설치 프로그램은 다음을 수행합니다:

• 기술(skills)을 .wednesday/skills/로 복사
• 에이전트 설정 파일(CLAUDE.md, GEMINI.md, .cursorrules, .github/copilot-instructions.md) 작성
• 자동 그래프 업데이트를 위한 git hooks(post-commit, post-merge) 설치
• 선택 사항인 커버리지(coverage) 및 Sonar 통합 프롬프트 제공
• Claude Code 탐색을 위해 기술(skills)을 ~/.claude/skills/에 심볼릭 링크(symlinks) 생성

Claude Code, Cursor 또는 Gemini CLI 내부에서 기술(skills)을 사용하는 데는 API 키가 필요하지 않습니다.
AI IDE 내부에서는 IDE가 인텔리전스 엔진 역할을 수행하며, 기술(skills)은 로컬 스크립트가 아닌 표준 지침(instructions)으로 작동합니다.

도구	설정 방법
Claude Code	CLAUDE.md
...

API 키는 독립형 CLI 워크플로우(plan, summarize, gen-tests)에서만 필요합니다.
대화형 설정 마법사를 실행하려면:

wednesday-skills config

또는 .env 파일에 수동으로 추가하세요:

OPENROUTER_API_KEY 또는 ANTHROPIC_API_KEY: 오프라인 LLM 기반 도구에서 사용됩니다.
GITHUB_TOKEN: PR 데이터를 가져오기 위해 wednesday-skills dashboard에서 사용됩니다.

| 기술 (Skill) | 기능 |\n|---|---|\ngit-os |\nConventional Commits (관습적 커밋)를 강제합니다 — 잘못되거나 모호한 커밋 메시지는 허용되지 않습니다.|\npr-review |\nGemini 수정 대기열 (fix queue) — PR 코멘트를 영향도에 따라 분류하고, 개발자의 승인 시 수정을 적용합니다.|\ndeploy-checklist |\n배포 전 점검 사항 및 배포 후 모니터링 체크리스트를 안내합니다.|\nwednesday-dev |\nImport 순서, 파일 복잡도 제한 (최대 8), 그리고 명명 규칙 (naming conventions)을 강제합니다.|\nwednesday-design |\n492개 이상의 승인된 UI 컴포넌트, 디자인 토큰 (design tokens), 그리고 애니메이션 패턴의 사용을 확인합니다.|\nsprint |\n티켓 ID를 Git 브랜치, PR 제목, 그리고 설명 템플릿으로 자동 변환합니다.|\ngreenfield |\n병렬 AI 페르소나 (Architect, PM, Security)가 몇 분 안에 종합적인 PLAN.md를 생성합니다.|\n\n| 기술 (Skill) | 기능 |\n|---|---|\nbrownfield-chat |\n구조적 그래프 (structural graphs)를 사용하여 일반 영어로 코드베이스 질의응답을 수행합니다 (환각 데이터 없음).\nbrownfield-query |\nSQLite (graph.db)로부터 의존성, 엔드포인트, 파일 메트릭을 반환하는 결정론적 구조적 쿼리 (deterministic structural queries)를 수행합니다.\nbrownfield-fix |\nAI가 파일을 수정하기 전에 위험 점수 (Risk score)와 영향 범위 (blast radius)를 계산합니다.\nbrownfield-drift |\nPLAN.md에 정의된 아키텍처 경계를 강제하여 도메인 침범 (domain spillage)을 방지합니다.\nbrownfield-gaps |\n국소화된 서브 에이전트 (subagents)를 통해 동적 런타임 그래프 커버리지를 향상시킵니다.|\n\n열려 있는 PR, 할당되지 않은 시맨틱 수정 대기열 (semantic fix queues), 설치된 기술 상태, 그리고 상세한 LLM 토큰 비용 내역을 추적할 수 있는 대화형 CLI 인터페이스를 제공합니다.\n\n모든 LLM 기반 명령 (map, summarize, gen-tests 등)은 실행 후 자동으로 비용 보고서를 출력합니다:\n\n\n━━━ 토큰 사용 보고서 (Token Usage Report) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n명령 (Command): map\nLLM 호출 (LLM calls): 18 (6개 캐시 히트 → 0 토큰)\n...\n\n\n**기준 비용 (Baseline)**은 Claude Sonnet ($3/M tokens)이 동일한 원본 소스 파일을 직접 읽을 때 소비할 비용으로 계산됩니다. **실제 비용 (Actual cost)**은 실제로 사용된 모델(예: gemini-2.5-flash-lite)을 반영합니다.

(예: $0.10/M). 이 차액은 사전 계산된 그래프(pre-computed graph)와 더 저렴한 모델 선택을 통해 얻은 절감액입니다.

→ 상세 내용: docs/token-cost-report.md

실제 코드 구조가 PLAN.md의 제약 사항을 안전하게 준수하는지 검증합니다.

(예: frontend-never-imports-db, no-circular-deps 등). PR(Pull Request) 과정에서 아키텍처의 퇴보(architectural decay)를 방지하기 위해 CI/CD 파이프라인에 통합되도록 설계되었습니다.

과거의 버그 수정 커밋(bug-fix commits)을 컨텍스트로 사용하여, 실제 호출자(callers)와 실제 AST(Abstract Syntax Tree) 모의 동작(mock behavior)을 활용해 포괄적인 테스트를 생성함으로써, 위험도가 높고 테스트 커버리지가 없는 파일들을 안전하게 래핑(wrap)합니다.

일상적인 영어 질문(예: "인증 레이어(auth layer)를 누가 작성했나요?", "X의 이름을 바꾸면 무엇이 깨지나요?")을 던지면, 로컬 AST 및 Git 히스토리에서 즉시 파싱된 검증된 답변을 받습니다. 오프라인 파싱을 사용하여 LLM 토큰을 100% 절약합니다.

모든 워크플로우는 Claude Code 또는 Gemini CLI 내부에서 완전히 실행됩니다. IDE는 사용자의 대화 내용을 바탕으로 관련 스킬(skills)을 원활하고 직관적으로 로드합니다.

시나리오: 아이디어가 있고 아키텍처적으로 견고한 계획이 필요한 경우.

사용자 발화: "이 프로젝트를 계획해줘: 실시간 협업 텍스트 에디터를 구축할 거야."
AI 동작: greenfield 스킬을 로드합니다. 프레임워크는 Architect, PM, Security AI 페르소나를 병렬로 실행합니다.
결과: 시스템 아키텍처, 보안 리스크, 단계별 티켓(phased tickets) 및 아키텍처 경계(architectural boundaries)를 포함하는 포괄적인 .wednesday/plans/PLAN.md 파일이 생성됩니다.
후속 작업: "첫 번째 티켓을 시작해줘."
→ sprint 스킬을 로드합니다. → Git 브랜치와 PR 초안을 자동으로 설정합니다.

시나리오: 문서화가 전혀 되어 있지 않은 레거시 코드베이스를 인계받은 경우.

사용자 발화: "이 코드베이스를 완전히 매핑해줘."
AI 동작: wednesday-skills map --full을 자동으로 트리거하여, 수천 개의 파일을 동적으로 파싱하고 고성능 .wednesday/graph.db 데이터베이스에 저장합니다.
결과: 전역 아키텍처 사용자 흐름(user flows)이 포함된 MASTER.md와 summaries.json을 생성합니다.

자연어 질의(natural language querying)를 위한 것입니다. 향후 작업에서는 수천 개의 토큰에 달하는 컨텍스트 파일(context files)을 전달할 필요가 없습니다. 에이전트가 미리 계산된 SQLite 그래프를 직접 질의하기 때문입니다.

시나리오: 새로운 개발자가 백엔드 API 팀에 합류하여 혼란을 겪고 있습니다.

당신의 명령: "백엔드를 위한 온보딩 가이드를 생성해줘."
AI 작업: onboard 의도(intent)를 해결하고, SQLite 재귀적 CTE(Recursive CTE) 프레임워크를 활용하여 CLI 진입점부터 핵심 도메인 로직(core domain logic)까지 깊게 중첩된 요청 흐름(request flows)을 네이티브하게 추적합니다.
결과: 개발자가 작업해야 하는 정확한 레이어에 특화되어, 매우 집중적이고 기능적인 단계별 Mermaid 다이어그램 실행 흐름과 읽기 가이드를 제공합니다.

시나리오: 거대하게 결합된(massively coupled) 모듈 깊숙한 곳의 버그를 수정하라는 업무를 맡았습니다.

당신의 명령: "auth.ts의 토큰 만료 버그를 수정해줘."
AI 작업: 코드를 작성하기 전에, graph.db 내에서 auth.ts의 **영향 범위(blast radius)**를 계산하기 위해 brownfield-fix를 선제적으로 호출합니다.
결과: 만약 해당 파일의 영향 점수(impact score)가 임계치(>80)를 초과하면, Claude는 강제로 동작을 멈추고 코드 수정을 거부하며, 연쇄적으로 영향을 받는 컴포넌트들을 명시적으로 나열합니다. 그리고 안전하게 진행하기 위해 개발자의 확인을 요청합니다. 승인이 완료되면, 깨끗한 git-os 스킬을 사용하여 커밋을 처리합니다.

시나리오: 리드 개발자가 당신의 Pull Request(PR)에 5개의 의미론적 코드 리뷰(semantic code review) 댓글을 남겼습니다.

당신의 명령: "@agent #2번과 #4번 수정해줘" 또는 "@agent 모두 수정해줘"
AI 작업: pr-review를 로드하여 정확한 GitHub 댓글을 파싱하고, 보안, 안전성 및 스타일 영향을 구조화하며, 각 수정 사항을 개별적이고 깔끔한 git 커밋으로 분리합니다.
결과: 커밋 히스토리를 오염시키거나 CI 체크를 깨뜨리지 않으면서 PR 피드백을 반복적으로 충족합니다.

시나리오: 미션 크리티컬(mission-critical) 모듈이 실시간 결제를 처리하지만 테스트 커버리지가 0%입니다.

당신의 명령: "테스트가 누락된 중요한 파일들에 대한 테스트를 생성해줘."
AI 작업: gen-tests --min-risk 75를 평가합니다.

테스트가 전혀 되어 있지 않으면서도 파급 효과(blast radius)가 매우 큰 코드를 순위화하기 위함입니다.결과: 환각에 기반한 스캐폴딩(scaffolding) 대신 결정론적 AST(Abstract Syntax Tree) 연결을 사용하여, 귀하의 프레임워크에 완벽하게 통합된 기능적인 모킹(mocked) .test.js 파일을 생성합니다.

# 설정 (Setup)
wednesday-skills install # 모든 에이전트 설치 + 구성
wednesday-skills config # 대화형 API 키 및 모델 설정
...

your-project/
├── CLAUDE.md # Claude Code Base 지침
├── GEMINI.md # Gemini Base 지침
...

전체 문서는 docs/ 폴더에 있습니다:

가이드	다루는 내용
시작하기 (Getting Started)	설치, 구성, 첫 번째 맵 생성, 권장 워크플로우
...	-

• 1단계: 설치, 구성, git hooks, 그린필드 플래너 (greenfield planner) ✓
• 2단계: 브라운필드 인텔리전스 (Brownfield intelligence) — 의존성 그래프 (dep graph), 리스크 점수, 요약, MASTER.md ✓
• 3단계: 채팅, 드리프트 탐지 (drift detection), 테스트 생성 ✓
• 4단계: 공개 레지스트리, 스킬 빌더, 사용 분석, 흐름 중심 자동화 (flow-centric automation) ✓
  현재 진행 중

라이선스: MIT — Wednesday Solutions