softspark/ai-toolkit

멀티 플랫폼을 지원하는 전문가급 AI 코딩 툴킷 (AI coding toolkit). 기계 기반의 안전성 강제 (Machine-enforced safety), 107개의 기술 (skills), 44개의 에이전트 (agents), 확장된 라이프사이클 훅 (lifecycle hooks), 페르소나 프리셋 (persona presets), 실험적 옵트인 플러그인 팩 (experimental opt-in plugin packs), 그리고 벤치마크 툴링 (benchmark tooling)을 제공합니다. Claude, Cursor, Windsurf, Copilot, Gemini, Cline, Roo Code, Aider, Augment, Google Antigravity, Codex CLI, opencode와 함께 작동하며 60초 안에 준비됩니다.

패치 릴리스 (Patch release). 검색 우선 강제 트리오 (search-first enforcement trio)의 세션 간 레이스 컨디션 (race condition) 문제를 수정했습니다: 단일 글로벌 search-required.flag가 모든 병렬 Claude Code 창에서 공유되어, 한 세션에서의 중지 (Stop) 동작이 다른 사용자의 프롬프트가 포함된 세션을 차단할 수 있었습니다. 또한 테스트 응집도 러너 (test-cohesion runner)에서의 bats 1.13 회귀 (regression) 문제를 해결했습니다.

세션별 검색 우선 플래그 (Per-session search-first flag): user-prompt-submit.sh, search-tracker.sh, stop-search-check.sh가 이제 session_id (search-required-<session_id>.flag)를 기준으로 플래그를 키(key)로 사용하므로, 병렬 Claude Code 창들이 더 이상 서로 간섭하지 않습니다.

만료된 플래그 가비지 컬렉션 (Stale-flag GC): session-start.sh가 60분 이상 된 세션별 플래그를 삭제하여, 충돌(crash)이 발생한 세션이 잔여물을 남기지 않도록 합니다.

bats 1.13 호환성: scripts/test_cohesion.py가 더 이상 --no-parallelize-within-files를 전달하지 않습니다 (이제 bats 1.13에서는 --jobs 2를 요구하며, 순차 모드에서는 어차피 불필요했습니다).

두 개의 새로운 격리 테스트 (Two new isolation tests): tests/test_search_first_flow.bats는 Stop 및 PostToolUse 경로 모두에 대해 세션별 플래그 스코핑 (scoping)을 검증합니다.

전체 이력은 CHANGELOG.md를 참조하세요.

• 설치 (Install)
• 플랫폼 지원 (Platform Support)
• 제공 기능 (What You Get)
• 아키텍처 (Architecture)
• 주요 기능 (Key Features)
• 주요 슬래시 명령어 (Key Slash Commands)
• 시작하기 (Getting Started)
• 문서 (Documentation)
• 기여하기 (Contributing)
• 보안 (Security)
• 라이선스 (License)
• 변경 이력 (Changelog)

# 옵션 A: 전역 설치 (기기당 1회)
npm install -g @softspark/ai-toolkit
ai-toolkit install
...

이것으로 끝입니다. Claude Code는 107개의 기술 (skills), 44개의 에이전트 (agents), 품질 훅 (quality hooks), 그리고 안전 헌법 (safety constitution)을 자동으로 인식합니다.

Windows: WSL을 권장 런타임 (runtime)으로 사용합니다. 훅 스크립트 (hook scripts)를 위해 Git Bash를 사용할 수 있는 경우 네이티브 Windows에서도 작동하며, 의존성 힌트 (dependency hints)는 winget을 포함합니다.

, Chocolatey, 그리고 Scoop을 포함합니다. Windows 지원 사항을 참조하세요.

npm install -g @softspark/ai-toolkit@latest && ai-toolkit update

cd your-project/
ai-toolkit install --local # Claude Code 전용
ai-toolkit install --local --editors all # + 모든 에디터
...

ai-toolkit plugin list # 사용 가능한 팩(packs) 표시
ai-toolkit plugin install --editor all --all # Claude + Codex를 위한 전체 설치
ai-toolkit plugin status --editor all # 설치된 항목 표시

ai-toolkit install --profile minimal # 에이전트 (agents) + 스킬 (skills)만 설치
ai-toolkit install --profile standard # 전체 설치 (기본값)
ai-toolkit install --profile strict # 전체 설치 + git hooks 포함

ai-toolkit validate # 무결성 검사
ai-toolkit doctor --fix # 자동 복구

모든 명령어와 옵션은 CLI Reference를 참조하세요.

플랫폼 (Platform)	설정 파일 (Config Files)	범위 (Scope)
Claude Code	~/.claude/	global
Cursor	.cursor/rules/*.mdc + .cursor/mcp.json	project (~/.cursor/mcp.json은 MCP 전용)
Windsurf	~/.codeium/.../global_rules.md + .windsurf/rules/*.md	global + project
Gemini CLI	~/.gemini/GEMINI.md	global
GitHub Copilot	.github/copilot-instructions.md	project
Cline	~/Documents/Cline/Rules/*.md + .clinerules/*.md	global + project
Roo Code	~/.roo/rules/*.md + .roomodes + .roo/rules/*.md	global rules + project
Aider	~/.aider.conf.yml + .aider.conf.yml + CONVENTIONS.md	global + project
Augment	~/.augment/rules/*.md + .augment/rules/ai-toolkit-*.md	global + project
Google Antigravity	.agent/rules/*.md + .agent/workflows/*.md	project
Codex CLI	AGENTS.md + .agents/rules/*.md + .agents/skills/* + .codex/hooks.json	project + global plugin
opencode	AGENTS.md + .opencode/{agents,commands,plugins}/* + opencode.json	project + global (~/.config/opencode/)

Claude Code는 항상 설치됩니다 (기본 플랫폼). 다른 에디터는 --editors 옵션을 통해 필요에 따라 설치할 수 있습니다.

모든 플랫폼은 동일한 에이전트/기술 (agent/skill) 카탈로그, 가이드라인 및 등록된 사용자 정의 규칙을 제공받습니다.

구성 요소	개수	설명
skills/ (task)	32	슬래시 명령어 (Slash commands): /commit, /build, /deploy, /test, /mcp-builder, ...
skills/ (hybrid)	30	에이전트 지식 베이스 (knowledge base)를 포함한 슬래시 명령어
skills/ (knowledge)	45	에이전트에 의해 자동 로드되는 도메인 지식 (13개의 <lang>-rules 기술 포함)
agents/	44	10개 카테고리에 걸친 특화된 에이전트 (specialized agents)
hooks/	22 global + 5 skill-scoped	품질 게이트 (Quality gates), 경로 안전성 (path safety), 프롬프트 거버넌스 (prompt governance), 세션 라이프사이클 (session lifecycle)
plugins/	11 packs	선택적 도메인 번들 (보안, 연구, 프론트엔드, 엔터프라이즈, 6개 언어 팩)
constitution.md	6 articles	기계에 의해 강제되는 안전 규칙 (Machine-enforced safety rules)
rules/	자동 주입 (auto-injected)	설정에 주입되는 언어별 및 사용자 정의 규칙
kb/	참조 문서 (reference docs)	아키텍처, 절차 및 모범 사례 (best practices)

ai-toolkit/
├── app/
│ ├── agents/ # 44개의 에이전트 정의
...

배포 (Distribution): 에이전트/기술은 심볼릭 링크 (Symlink) 기반이며, 훅 (hooks)은 복사 (copy) 기반입니다. npm install 이후 ai-toolkit update를 실행하세요 — 모든 프로젝트에 변경 사항이 즉시 반영됩니다. 배포 모델 (Distribution Model)을 참조하세요.

기계에 의해 강제되는 헌법 (Machine-enforced constitution) — PreToolUse 훅을 통해 강제되는 6개 조항의 안전 헌법입니다. 이는 단순히 문서에 그치지 않고, 실제로 rm -rf, DROP TABLE 및 되돌릴 수 없는 작업들을 차단합니다.

28개의 라이프사이클 훅 (lifecycle hooks) — 14개의 이벤트(SessionStart → SessionEnd, 그리고 InstructionsLoaded + ConfigChange 포함)에 걸쳐 실행 가능한 스크립트입니다. 가드 (Guards), 거버넌스 (governance), 품질 게이트 (quality gates), 세션 지속성 (session persistence), MCP 상태 확인 (health checks), 되돌리기 방지 (revert protection), 테스트 응집력 강제 (test-cohesion enforcement), 검색 우선 원칙 (search-first discipline)을 담당합니다. 훅 카탈로그 (Hooks Catalog)를 참조하세요.

보안 스캐닝 (Security scanning) — 코드 수준의 위험을 위한 /skill-audit, 의존성 CVE를 위한 /cve-scan을 제공합니다. 두 기능 모두 종료 코드 (exit codes)를 지원하여 CI 환경에 즉시 적용 가능합니다.

철칙 강제 (Iron Law enforcement) — /tdd, debugging-tactics, 그리고 verification-before-completion (완료 전 검증).

anti-rationalization (자기합리화 방지) 테이블을 통해 타협 불가능한 게이트 (gates)를 강제합니다. 자기합리화 저항 (rationalization resistance)을 포함하여 총 15개의 기술 (skills)이 포함되어 있습니다.

다국어 품질 게이트 (Multi-language quality gates) — Stop

모든 응답 후에 Python, TypeScript, PHP, Dart, Go에 대해 lint 및 타입 체크 (type checks)를 실행합니다.

에이전트 검증 체크리스트 (Agent verification checklists) — 10개의 에이전트에는 결과를 제시하기 전에 반드시 충족해야 하는 종료 기준 (exit criteria)이 포함되어 있습니다.

2단계 리뷰 (Two-stage review) — /subagent-development

작업별로 Implementer → Spec Review → Quality Review 과정을 실행합니다.

지속성 메모리 (Persistent memory) — memory-pack

플러그인: 과거 세션 전체에 대한 SQLite + FTS5 검색을 지원합니다.

로컬 제품 텔레메트리 (Local product telemetry) — ai-toolkit stats --summary

로컬 사용 데이터를 기반으로 총 호출 횟수 (invocations), 기술 커버리지 (skill coverage), 사용되지 않은 카탈로그 기술, 최근 활동 및 상위 기술을 보고합니다.

페르소나 프리셋 (Persona presets) — 4가지 역할 (backend-lead, frontend-lead, devops-eng, junior-dev)이 스타일과 우선순위를 조정합니다.

설정 상속 (Config inheritance) — Enterprise extends

헌법 불변성 (constitution immutability) 및 강제 제약 조건 (enforcement constraints)을 갖춘 시스템입니다. Enterprise Config Guide를 참조하세요.

70개 언어 규칙 (70 language rules) — 13개 언어 + 공통 언어, 각 5개 카테고리. 자동 감지 또는 명시적인 --lang 옵션을 사용합니다. Language Rules를 참조하세요.

26개 MCP 템플릿 (26 MCP templates) — GitHub, PostgreSQL, Slack, Jira, Sentry 등을 위한 즉시 사용 가능한 설정입니다. MCP Templates를 참조하세요.

모든 차별화 요소에 대한 자세한 설명은 Unique Features를 참조하세요.

명령 (Command)	목적 (Purpose)	노력 (Effort)
/workflow <type>	사전 정의된 멀티 에이전트 워크플로우 (15가지 유형)	최대 (max)
/orchestrate	사용자 정의 멀티 에이전트 조정 (3–6개 에이전트)	최대 (max)
/swarm	병렬 에이전트 팀: map-reduce, consensus, relay	최대 (max)
/plan	작업 분할을 포함한 구현 계획 (Implementation plan)	높음 (high)
/review	코드 리뷰 (Code review): 품질, 보안, 성능	높음 (high)
/debug	진단 도구를 활용한 체계적인 디버깅 (Debugging)	중간 (medium)
/refactor	패턴 분석을 통한 안전한 리팩토링 (Refactoring)	높음 (high)
/tdd	Red-Green-Refactor 방식의 테스트 주도 개발 (Test-driven development)	높음 (high)
/commit	린팅 (Linting)을 포함한 구조화된 커밋 (Commit)	중간 (medium)
/pr	생성된 체크리스트를 포함한 풀 리퀘스트 (Pull request)	중간 (medium)
/docs	README, API 문서, 아키텍처 노트 생성	높음 (high)
/explore	대화형 코드베이스 시각화 (Codebase visualization)	중간 (medium)
/write-a-prd	대화형 인터뷰를 통한 제품 요구 사항 문서 (PRD) 작성	높음 (high)
/prd-to-plan	PRD를 수직적 슬라이스 (Vertical-slice) 구현 계획으로 변환	높음 (high)
/design-an-interface	3개 이상의 근본적으로 다른 인터페이스 디자인 생성	높음 (high)
/grill-me	소크라테스식 질문법 (Socratic questioning)을 통한 계획 스트레스 테스트	중간 (medium)
/triage-issue	심층 조사 및 TDD 수정 계획을 통한 버그 분류 (Triage)	높음 (high)
/architecture-audit	얕은 모듈 발견 및 리팩토링 제안	높음 (high)
/council	4가지 관점의 의사 결정 평가	높음 (high)
/cve-scan	알려진 CVE(Common Vulnerabilities and Exposures)에 대한 종속성 스캔	중간 (medium)
/skill-audit	보안 위험에 대한 기술/에이전트 스캔	중간 (medium)
/repeat	안전 제어 장치가 포함된 자율 루프 (Autonomous loop)	중간 (medium)
/persona	런타임 시 엔지니어링 페르소나 (Persona) 전환	낮음 (low)

feature-development backend-feature frontend-feature
api-design database-evolution test-coverage
security-audit codebase-onboarding spike
...

멀티 에이전트 조정 (Multi-agent coordination)이 필요한가요?
├── 도메인을 알고 있습니까? → /orchestrate (임시, 3-6개 에이전트)
├── 알려진 패턴이 있습니까? → /workflow <type> (15개 템플릿)
...

• CLAUDE.md 커스터마이징— 프로젝트의 기술 스택 (tech stack), 명령어, 그리고 컨벤션 (conventions)을 상단 (toolkit 마커 위)에 추가하세요.

• 스킬 (skills) 사용 시작: /onboard # 가이드 기반 설정 인터뷰 /explore # 코드베이스 이해 /plan # 기능 계획

설치 확인: ai-toolkit validate

주제	링크
CLI 레퍼런스 (CLI Reference)	kb/reference/cli-reference.md
...

CONTRIBUTING.md를 참조하세요.

책임 있는 공개 정책 (responsible disclosure policy)에 대해서는 SECURITY.md를 참조하세요.

MIT — LICENSE를 참조하세요.

CHANGELOG.md를 참조하세요.

SoftSpark의 실제 운영 환경에서 추출되었습니다. 우리가 존재하기를 바랐던 툴킷이 되도록 제작되었습니다.