iliaal/whetstone

AI 코딩 에이전트가 엔지니어링 규율 (engineering discipline)을 따르도록 만드는 Claude Code 플러그인입니다. 코딩하기 전에 계획하고, 완료를 주장하기 전에 검증하며, 패치하기 전에 근본 원인을 찾고, 병합하기 전에 리뷰하십시오. 기술은 수동으로 전환하는 것이 아니라 파일 유형과 작업 신호에 따라 활성화됩니다.

PHP, Python, TypeScript, React 및 인프라 워크플로우를 위한 에이전트, 기술, 워크플로우 명령 및 기술 증류기 (skill distillery)를 번들로 제공합니다.

Claude Code를 실제 업무에 사용하는 팀. PHP, Python, TypeScript 또는 React로 빌드하고 계신가요? 에이전트가 구축하기 전에 계획하고, 배포하기 전에 검증하며, 추측 대신 추론을 통해 디버깅하기를 원하시나요? 이 플러그인이 그 구조를 제공합니다.

일관성을 원하는 개인 개발자. Bash 스크립트를 작성하면 에이전트가 set -Eeuo pipefail 및 ShellCheck 준수를 강제합니다. Laravel 컨트롤러를 수정하면 엄격한 타입 (strict types) 및 씬 컨트롤러 (thin-controller) 패턴을 적용합니다. 설정도, 전환도 필요 없습니다.

AI 에이전트로 무언가를 구축하는 모든 사람. 멀티 에이전트 오케스트레이션 (multi-agent orchestration), 에이전트 네이티브 아키텍처 설계 (agent-native architecture design)를 위한 기술과 커뮤니티의 높은 평가를 받은 소스로부터 새로운 기술을 생성하는 증류기를 포함합니다.

AI 코딩 에이전트는 계획을 건너뛰고, 검증 없이 "완료"라고 주장하며, 근본 원인 대신 증상만을 패치하고, 컨텍스트가 리셋되면 배운 내용을 잊어버립니다. 결과물은 다듬어진 것처럼 보이지만, 그 내부 동작은 규율이 없습니다.

상세한 논거는 "AI 에이전트는 능력이 부족한 것이 아니라 프로세스가 부족한 것이다 (AI Agents Don't Lack Capability. They Lack Process.)"에서 확인할 수 있습니다. 이 플러그인은 그 프로세스를 강제합니다.

/plugin marketplace add https://github.com/iliaal/whetstone
/plugin install whetstone@iliaal-marketplace
/reload-plugins

개별 기술은 ai-skills 리포지토리를 통해 Claude Code, Cursor, Codex, Gemini CLI, Copilot CLI, OpenCode 및 35개 이상의 다른 에이전트와 함께 작동합니다:

# 모든 기술
npx skills add iliaal/ai-skills
# 단일 기술
...

Codex의 네이티브 플러그인 사양은 아직 커스텀 에이전트를 등록하지 않으므로, Claude 플러그인 소스로부터 Codex 네이티브 출력을 생성하는 Bun/TypeScript 컨버터를 제공합니다. 전제 조건: 로컬 클론 및 bun 설치가 필요합니다.

git clone https://github.com/iliaal/whetstone
cd whetstone
bun install
...

기본적으로 컨버터는 Codex 스킬 (skills) 및 에이전트 (agents)를 ~/.codex/ 아래에 작성합니다.

--codex-home ~/path/to/.codex를 사용하여 기본값이 아닌 Codex 설치 경로를 대상으로 지정할 수 있습니다. 에이전트에 대한 네이티브 Codex 플러그인 지원이 도입되면, 이 변환 단계는 불필요해집니다.

재설치하기 전(또는 이 플러그인에서 다른 것으로 전환하기 전)에 오래된 아티팩트 (artifacts)를 백업하십시오:

bun run src/index.ts cleanup --target codex # ~/.codex/skills 및 ~/.codex/prompts를 타임스탬프가 찍힌 백업으로 이동합니다
bun run src/index.ts cleanup --target codex --dry-run # 미리보기만 수행합니다

백업은 ~/.cache/whetstone/legacy-backup/ 아래에 저장됩니다.

동일한 컨버터이지만 대상이 다릅니다. OpenCode는 각 프로젝트별 설정에서 스킬을 읽습니다. 컨버터는 플러그인의 SKILL.md 형식을 OpenCode가 기대하는 형태로 번역하여 현재 프로젝트에 출력물을 작성합니다 (--output <dir>로 재지정 가능).

bun run src/index.ts install ./plugins/whetstone --to opencode

--also codex를 전달하면 한 번의 실행으로 Codex와 OpenCode 출력물을 모두 생성할 수 있습니다.

OpenCode(및 기타 대상)를 위한 정리 (Cleanup) 작업도 동일한 명령어를 사용합니다:

bun run src/index.ts cleanup --target opencode
bun run src/index.ts cleanup --target kilocode
bun run src/index.ts cleanup --target agents

~/.agents/skills, ~/.codex/skills, 또는 ~/.kilocode/skills에서 스킬을 직접 읽는 도구들을 위해, scripts/sync-to-tools.sh는 플러그인의 스킬 디렉토리를 각 경로에 심볼릭 링크 (symlinks)로 연결하여, 재변환 없이도 수정 사항이 즉시 반영되도록 합니다. 이는 프로덕션 설치가 아닌 활발한 개발을 위해 의도된 기능입니다.

bash scripts/sync-to-tools.sh # 세 가지 도구 디렉토리 모두에 심볼릭 링크 생성
bash scripts/sync-to-tools.sh --dry-run # 변경 사항 미리보기

codesage는 구조적 코드 인텔리전스(심볼, 참조, 의존성 찾기, 영향 범위 분석 (blast-radius analysis))를 MCP 서버로서 추가합니다. 이 플러그인은 규율을 강제하며, codesage는 에이전트가 그 규율을 적용할 수 있도록 코드베이스의 지도를 제공합니다. ai-skills는 이 플러그인의 기술을 읽기 전용 미러 (read-only mirror)로 만든 것으로, Claude Code가 아닌 에이전트들을 위해 패키징되었습니다. Claude Code를 사용 중이라면 플러그인을 사용하고, Cursor, Codex, Gemini CLI 또는 이와 유사한 도구를 사용 중이라면 미러를 사용하세요.

다섯 가지 명령어가 하나의 루프를 형성합니다: 문제를 탐색하고, 해결책을 계획하며, 구축하고, 검토하고, 배운 내용을 문서화합니다. 각 단계가 반복될수록 해결책이 검색 가능한 문서로 축적되기 때문에 다음 단계는 더 빨라집니다.

명령어	기능
/ia-brainstorm	숨겨진 요구사항을 드러내기 위해 한 번에 하나씩 질문을 던지며 인터뷰를 진행합니다. 트레이드오프 (trade-offs)가 포함된 2~3개의 명명된 접근 방식을 생성합니다. 설계 문서 (design doc)가 승인될 때까지 코드를 작성하지 않습니다.
/ia-plan	브레인스토밍 결과나 기능 아이디어를 원자적 작업 (atomic tasks), 특정 파일 경로, 그리고 수직적 슬라이스 (vertical slices) 형태의 단계별 전달을 포함하는 파일 기반 계획으로 변환합니다.
/ia-work	작업 추적, 워크트리 격리 (worktree isolation), 검증 게이트 (verification gates)와 함께 계획을 실행합니다. 각 작업은 완료로 표시되기 전에 빌드/테스트를 거칩니다.
/ia-review	멀티 에이전트 코드 리뷰: 범위 이탈 (scope-drift) 탐지, 사양 준수 여부, 코드 품질, 보안, 성능을 검토합니다. 복잡한 디프 (diffs)가 발생하면 자동으로 딥 모드 (deep mode)로 격상됩니다.
/ia-compound	방금 해결한 내용을 docs/solutions/에 검색 가능한 문서로 캡처하여, 다음 사람(또는 에이전트)이 동일한 문제를 다시 디버깅하지 않도록 합니다.

다섯 가지를 모두 사용할 필요는 없습니다. /ia-review만 단독으로 사용해도 견고한 병합 전 체크 (pre-merge check) 도구가 됩니다. /ia-plan은 범위를 정하는 용도로 단독 사용이 가능합니다. 상황에 맞춰 조합하여 사용하세요.

기술 (Skills)은 작업 중인 내용에 따라 활성화되는 지침입니다. 이는 지식을 추가하기보다는 절차와 안티 패턴 (anti-patterns)을 강제함으로써 에이전트가 행동하는 방식을 형성합니다.

기술 (Skill)	설명 (Description)
ia-agent-native-architecture	AI 에이전트가 주요 행위자인 시스템을 위한 15개 영역 아키텍처 체크리스트: 도구 설계 (tool design), 실행 패턴 (execution patterns), 컨텍스트 주입 (context injection), 승인 게이트 (approval gates), 감사 추적 (audit trails). 에이전트 시스템 또는 MCP 도구를 설계하기 위한 용도.
...	...
기술 (Skill)	설명 (Description)
---	---
ia-react-frontend	"useEffect를 사용해야 할까?"라는 질문의 대부분을 비-이펙트 (non-effect) 솔루션으로 라우팅하는 결정 트리. 목적에 따라 상태 도구를 분리 (클라이언트는 Zustand, 서버는 React Query, URL은 nuqs). React 19 패턴, App Router의 서버/클라이언트 경계 준수, 그리고 Server Actions가 공개 엔드포인트임을 명시. React, Next.js, 그리고 Vitest/RTL 테스트를 위한 용도.
...	...
기술 (Skill)	설명 (Description)
---	---
ia-postgresql	SERIAL 대신 BIGINT GENERATED ALWAYS AS IDENTITY 사용, TIMESTAMP 대신 TIMESTAMPTZ 사용, 모든 외래 키 (FK)에 인덱스 생성 (Postgres는 이를 자동으로 생성하지 않음). 인덱스가 없는 FK를 탐지하는 쿼리를 포함하며, 모든 최적화 주장 전에 EXPLAIN (ANALYZE, BUFFERS) 실행을 의무화함. 스키마 설계, 쿼리 튜닝, RLS 또는 파티셔닝 (partitioning)을 위한 용도.
...	...
기술 (Skill)	설명 (Description)
---	---
ia-writing-tests	DRY 대신 DAMP 원칙 적용, 구현 세부 사항이 아닌 사용자 여정 (user journeys) 기반의 테스트 케이스 작성, 모의 객체 (mocks) 대신 실제 객체 사용 (모의 객체는 시스템 경계에서만 사용). 버그 수정 테스트를 위한 레드-그린 (red-green) 사이클 요구. 테스트를 건너뛰고 싶은 유혹이 들 때를 위한 '13가지 변명 합리화 표' 포함. 모든 언어와 호환.
...	...
기술 (Skill)	설명 (Description)
---	---
ia-brainstorming	엄격한 게이트: 설계 문서 (design doc)가 승인될 때까지 코드 작성 금지. 코드베이스를 먼저 읽고, 한 번에 하나씩 질문하며 인터뷰를 진행하고, 트레이드오프 (trade-offs)가 포함된 2~3개의 명명된 접근 방식을 제안한 뒤, docs/brainstorms/에 구조화된 문서를 저장함. 모호한 요구사항이나 여러 가지 유효한 해석이 가능한 경우를 위한 용도.
...	...
기술 (Skill)	설명 (Description)
---	---
ia-meta-prompting	슬래시 명령어를 통한 추론 패턴: /ia-verify는 도전 및 검증 (challenge-and-verify) 추가, /adversarial은 순위가 매겨진 반론 생성, /edge는 파괴 시나리오 (break scenarios) 열거, /confidence는 각 주장별 점수 할당.

컨텍스트 내의 일부 자동 트리거. 의사결정에 대한 스트레스 테스트 (stress-testing) 또는 숨겨진 가정 (hidden assumptions)을 드러내기 위한 용도. |
| ... |

기술 (Skill)	설명
ia-orchestrating-swarms	수명이 짧은 하위 에이전트 (subagents)와 지속적인 팀원을 구분하고, 각각을 언제 사용할지 규정하며, 다음과 같은 배정 규율 (dispatch discipline)을 강제합니다: 병렬 구현을 위한 워크트리 격리 (worktree isolation), 위임된 탐색 대신 직접적인 컨텍스트 사용, 실패한 작업에 대한 새로운 에이전트 투입. 4가지 표준화된 상태 신호 제공. 병렬 처리를 통해 이점을 얻을 수 있을 만큼 충분히 큰 작업에 적합함.

메인 에이전트 또는 워크플로 명령에 의해 배정되는 특화된 하위 에이전트 (subagents). 각 에이전트는 고유한 도구 및 컨텍스트와 함께 격리된 상태로 실행됩니다.

에이전트 (Agent)	설명
ia-accessibility-tester	키보드 탐색, 스크린 리더 호환성, 대비 비율 (contrast ratios), ARIA 속성 및 양식 접근성을 포함한 WCAG 2.1 감사 (audit). 출시 전 준수 사항 확인용.
...
에이전트 (Agent)	설명
---	---
ia-best-practices-researcher	모든 기술에 대해 공식 프레임워크 문서, 버전별 베스트 프랙티스 (best practices) 및 산업 표준을 수집합니다.
...
에이전트 (Agent)	설명
---	---
ia-design-iterator	스크린샷-분석-개선 사이클을 통한 반복적인 UI 개선. 초기 디자인 변경이 평범한 결과를 초래할 때 사용.
ia-figma-design-sync	구현된 UI를 Figma 디자인과 비교하고, 불일치 사항을 보고하며, 선택적으로 수정 사항을 적용합니다.

에이전트 (Agent)	설명
ia-bug-reproduction-validator	버그 보고를 재현하고 수정을 적용하지 않은 채 근본 원인 (root causes)을 식별합니다. 엔지니어가 투입되기 전 보고 내용이 실제 버그인지 검증합니다.
...
모든 명령은 Claude Code 내장 기능 및 형제 플러그인과의 충돌을 방지하기 위해 ia- 접두사를 포함합니다. 전체 목록은 다음과 같습니다:

명령 (Command)	설명 (Description)
/ia-brainstorm	계획을 세우기 전, 일대일 인터뷰를 통해 요구사항과 접근 방식을 탐색합니다.
/ia-plan	기능 아이디어를 원자적 작업 (atomic tasks) 및 수직적 슬라이스 (vertical slices)를 포함한 파일 기반 구현 계획으로 전환합니다.
/ia-work	작업 추적 (task tracking), 워크트리 격리 (worktree isolation) 및 검증 게이트 (verification gates)를 통해 계획을 실행합니다.
/ia-review	멀티 에이전트 (Multi-agent) 코드 리뷰: 범위 이탈 (scope-drift) 탐지, 사양 준수 (spec compliance), 코드 품질, 보안, 성능을 검토합니다.
/ia-compound	해결된 문제들을 docs/solutions/ 내에 검색 가능한 문서로 캡처합니다.
/ia-document-release	배포 후 README, ARCHITECTURE, CONTRIBUTING, CHANGELOG 전반에 걸쳐 문서를 동기화합니다.

명령 (Command)	설명 (Description)
/ia-lfg	완전 자율 워크플로우 (Full autonomous workflow): 계획, 빌드, 리뷰, 배포. 병렬 실행을 위해 --swarm을 사용합니다.
/ia-verify	PR 전 검증 파이프라인 (Pre-PR verification pipeline): 빌드, 타입 (types), 린트 (lint), 테스트, 보안 스캔, 차이점 리뷰 (diff review).
/ia-resolve-pr	클러스터 분석 (cluster analysis) 및 병렬 에이전트를 통해 PR 리뷰 코멘트를 일괄 해결합니다.
/ia-deepen-plan	각 섹션에 대해 병렬 조사 에이전트 (parallel research agents)를 사용하여 기존 계획을 강화합니다.
/ia-ideate	코드베이스를 스캔하여 순위가 매겨진 개선 아이디어를 생성한 후, 확산적 아이디어 구상 (divergent ideation) 및 적대적 비판 (adversarial critique)을 수행합니다.
/ia-setup	프로젝트 스택을 자동 감지하고 실행할 리뷰 에이전트를 구성합니다.
/ia-adr	형식 선택 및 생명주기 관리가 포함된 아키텍처 결정 기록 (Architecture Decision Records, ADR)을 생성합니다.
/ia-test-browser	현재 PR 또는 브랜치에 영향을 받는 페이지에서 브라우저 테스트를 실행합니다.
/ia-feature-video	기능에 대한 비디오 워크스루 (walkthrough)를 녹화하여 PR 설명에 추가합니다.
/ia-compound-refresh	docs/solutions/를 검토하여 오래된 학습 내용을 확인합니다: 유지, 업데이트, 교체 또는 아카이브합니다.
/ia-changelog	최근 머지 (merges)를 바탕으로 변경 로그 (changelogs)를 작성합니다.
/ia-reproduce-bug	로그와 콘솔 출력을 사용하여 버그를 재현합니다.
/ia-report-bug	플러그인의 버그를 보고합니다.
/ia-triage	이슈를 분류 (Triage)하고 우선순위를 지정합니다.

| /ia-resolve-todo-parallel | todos/ 디렉토리의 모든 미결 TODO 항목을 병렬로 해결합니다. |
| /ia-agent-native-audit | 점수가 매겨진 원칙 (scored principles)을 사용하여 에이전트 네이티브 (agent-native) 아키텍처 리뷰를 실행합니다. |

기술 (Skills)은 컨텍스트 (context)를 소비합니다. 기술이 사용하는 모든 토큰은 에이전트가 당신의 코드를 위해 사용할 수 없는 토큰입니다. 따라서 이들은 매우 타이트하게 구축되었습니다:

1K 토큰 미만, 최대 2K 제한. 초과분은 references/ 파일로 온디맨드 (on demand) 로드됩니다.
프론트 로딩 (Front-loaded). 중요한 규칙을 먼저 배치합니다. 모델의 주의력 (attention)은 떨어지기 때문에, 중요한 내용이 앞서야 합니다.
설명이 아닌 행동 (Actions, not explanations). 사물이 무엇인지가 아니라 에이전트에게 무엇을 해야 하는지 말하세요. 모델이 이미 알고 있는 것은 건너뜁니다.
모든 "하지 마세요"에는 "대신 이렇게 하세요"가 있습니다. 단순한 금지는 에이전트를 추측하게 만듭니다. 대안은 명확한 경로를 제공합니다.
키워드가 풍부한 설명. 설명은 설치된 모든 기술 전체에서 시작 시 로드되는 유일한 부분입니다. 에이전트는 이를 사용하여 기술을 활성화할지 여부를 결정하므로, 개발자들이 입력하는 정확한 문구들로 가득 채워져 있습니다. 본문은 트리거될 때만 로드됩니다.

distillery/ 디렉토리는 기술을 생성, 평가 및 진화시키기 위한 파이프라인입니다. 이는 평점이 높은 커뮤니티 기술을 가져오고, 중복되는 조언을 분석하며, 불필요한 내용을 제거하고, 모순을 해결하며, 주제당 하나의 집중된 지침 세트로 합성합니다.