AI 어시스턴트에게 PR(Pull Request) 리뷰를 요청했을 때, 보안 영향, 테스트 커버리지 공백, 특정 패턴 위반 사항 등 정말 철저한 답변을 받았던 경험이 있으신가요? 그런데 다음 주에 똑같은 질문을 했을 때 고작 다섯 개의 불렛 포인트(bullet points)만 받는 그런 기분 말입니다.

그것은 버그가 아닙니다. 모델은 철저한 리뷰를 어떻게 하는지 알고 있습니다. 단지 일관되게 수행하지 못할 뿐입니다.

저는 6주 동안 로그를 기록했습니다. Claude의 코드 리뷰 품질은 동일한 코드베이스를 사용하더라도 세션마다 크게 달랐습니다. 상세한 CLAUDE.md를 작성해 보기도 했습니다. 도움이 되긴 했지만 — 노트북을 교체하면서 복사하는 것을 잊어버리기 전까지만 말이죠. 그 후 제 동료는 약간 다른 버전을 가지고 있었습니다. 우리는 실수로 AI 어시스턴트의 동작을 포크(fork)해 버린 셈입니다.

그래서 저는 grimoire를 만들었습니다. 🧙

📦 grimoire란 무엇인가?

npm과 비슷하지만, AI 에이전트의 베스트 프랙티스(best practices)를 위한 것이라고 생각하면 됩니다.

grimoire.toml 파일에 원하는 기술 라이브러리(skill libraries)를 선언합니다. Grimoire는 git 레지스트리에서 이를 클론(clone)하고, 개별 기술 파일들을 각 AI 에이전트의 컨텍스트(context) 디렉토리에 심볼릭 링크(symlink)로 연결합니다. 기술들은 Claude에서는 슬래시 커맨드(slash commands)로, Codex에서는 탭 완성(tab-completable)이 가능한 명령어로 나타나며, 다른 에이전트에서도 마찬가지로 작동합니다.

그다음 grimoire check를 실행하면, 단순히 코드를 어떻게 짜느냐가 아니라 어떻게 일하느냐에 대한 설치된 프랙티스들을 기준으로 프로젝트를 감사(audit)합니다 — 마치 ESLint와 같은 방식입니다.

# grimoire 설치
curl -fsSL https://raw.githubusercontent.com/jeffreytse/grimoire/main/scripts/install.sh | bash

...

이것이 전체 루프(loop)입니다.

🚀 설치부터 첫 번째 감탄까지

grimoire install을 실행하면, 기술들이 즉시 슬래시 커맨드로 나타납니다. 엔지니어링 기술 라이브러리를 설치한 후의 코드 리뷰 모습은 다음과 같습니다:

사용자: /conduct-code-review

Claude: 선언된 엔지니어링 표준에 따라 스테이징된 변경 사항을 리뷰하는 중...
...

단 다섯 개의 불렛 포인트가 아닙니다. 매번 파일 위치와 기준이 포함된 구조화된 판결을 내립니다.

🧠 어떤 기술을 호출해야 할지 알 필요는 없습니다

이 부분이 제가 가장 좋아하는 부분입니다. 기술 이름을 외울 필요가 없습니다. 상황을 설명하기만 하면 적절한 실무(practice)로 안내하는 마법서(grimoire)가 경로를 안내합니다:

사용자: 우리 팀이 계속 스프린트 목표를 놓치고 있는데 이유를 모르겠어요.

Claude: 상황 일치: plan-retrospective (engineering/project-management)
...

사용자: 48시간 후에 출시인데 무언가 고장 날까 봐 너무 두렵습니다.

Claude: 상황 일치: apply-premortem (engineering/reliability)
...

suggest-best-practice는 어떤 상황이든 자동으로 분류하고 경로를 지정합니다. 만약 관련 기술이 설치되어 있지 않다면, grimoire.toml에 정확히 무엇을 추가해야 하는지 알려줍니다.

🗂️ 기술(skills)이 실제로 작동하는 방식

기술은 단일 마크다운 (markdown) 파일입니다. 프롬프트 (prompt)가 아니라 런북 (runbook)에 더 가깝습니다:

---
name: conduct-code-review
tags: [engineering, review]
...

모든 기술은 트리거 조건 (triggering condition), 인용된 출처 (cited source), 번호가 매겨진 단계 (numbered steps), 그리고 판결 양식 (verdict form)을 가지고 있습니다. 단순한 제안이 아니라 하나의 절차 (procedure)입니다.

제가 영리하다고 생각하는 부분은 이겁니다: AI에게 코드 리뷰 (code review) 방법을 가르치는 바로 그 파일이, 프로젝트에서 실제로 리뷰를 수행했는지 감사(auditing)할 때 grimoire check가 읽는 파일이기도 합니다. 별도로 유지 관리해야 하는 컴플라이언스 스키마 (compliance schema)가 없습니다. 기술을 업데이트하면 가이드라인과 컴플라이언스 기준 (compliance criteria)이 한 번에 업데이트됩니다.

🔍 컴플라이언스 엔진 — grimoire check

grimoire check는 흥미로운 지점입니다.

grimoire check                     # 전체 프로젝트 감사 (full project audit)
grimoire check --live              # 워치 모드 (watch mode): 파일 저장 시마다 재검사
grimoire check --scope changed     # 증분 (incremental) — 변경된 파일만 검사 (대규모 리포지토리(repo)에 유용)
...

출력 예시:

$ grimoire check

  ✓  propose-conventional-commit   100%  4개 기준 모두 통과
...

이를 통해 CI (지속적 통합)의 게이트 (gate)를 설정할 수 있습니다. grimoire.toml에 임계값 (threshold)을 선언하세요:

[standards]
threshold = 80  # 컴플라이언스 80% 미만일 경우 CI 실패

다른 린터(linter)와의 차이점: ESLint는 코드가 유효한 JavaScript인지 확인합니다. 반면 grimoire check는 프로젝트가 당신이 선언한 관행(practices)을 실제로 준수하는지 확인합니다. 최근 5개의 커밋이 컨벤셔널 커밋(conventional commit) 형식을 사용했나요? 새로운 인증(auth) 모듈이 당신의 표준에 부합하는 충분한 테스트 커버리지(test coverage)를 갖추었나요? PR에 보안 체크리스트가 포함되었나요? 이것들은 의미론적인(semantic) 질문들이며, 기존의 린터들은 이에 답할 수 없습니다.

🖥️ 에디터 통합 (LSP)

grimoire lsp는 언어 서버 프로토콜(Language Server Protocol, LSP)을 구현합니다. LSP를 지원하는 에디터를 여기에 연결하면, 모든 파일을 저장할 때마다 거터(gutter)에서 컴플라이언스 진단 결과를 확인할 수 있습니다.

Neovim:

if not configs.grimoire then
  configs.grimoire = {
    default_config = {
...

Helix:

[[language-server]]
name = "grimoire"
command = "grimoire"
...

일회성 언어 클라이언트(language client) 설정 외에 별도의 플러그인은 필요하지 않습니다. VSCode도 지원됩니다.

🤖 MCP 서버 — AI가 스스로를 관리하게 하세요

grimoire mcp serve는 모든 grimoire 작업을 MCP 도구로 노출합니다. Claude Desktop, Cursor, 또는 Windsurf는 대화 도중에 자신의 스킬 라이브러리를 직접 관리할 수 있습니다:

grimoire mcp serve   # MCP 서버 시작
grimoire mcp config  # 에디터에 설정 파일 작성

AI는 grimoire_install, grimoire_update, grimoire_check를 도구 호출(tool calls)로 실행할 수 있습니다. 즉, 사용자가 터미널을 건드리지 않아도 누락된 스킬을 감지하고, 이를 설치한 뒤 즉시 적용할 수 있습니다.

🌍 엔지니어링만을 위한 것이 아닙니다

제가 계속해서 강조해야 하는 부분은 이것입니다: grimoire-core는 27개 도메인에 걸쳐 1000개 이상의 스킬을 제공합니다.

엔지니어링, 아키텍처, 제품 관리(Product management), 기술 문서 작성(Technical writing), 법률 검토(Legal review), 재무 분석(Financial analysis), 건강, 리더십, 영업, 요리까지 포함됩니다.

코드 리뷰 표준을 강제하는 것과 동일한 인프라가 법률 문서 검토, 재무 실사(financial due diligence), 임상 프로토콜 준수, 또는 온보딩 문서의 품질을 강제할 수 있습니다. 메커니즘은 동일하며, 단지 스킬만 바뀔 뿐입니다.

그것이 더 큰 도박입니다. AI는 모두에게 이해력 (comprehension)을 제공합니다. Grimoire는 모두에게 실천 능력 (practice)을 제공합니다. 시니어 변호사의 검토 체크리스트, 숙련된 엔지니어의 PR (Pull Request) 프로세스, McKinsey 컨설턴트의 구조화 프레임워크 — 이들은 독점적인 것이 아니라, 단지 이전에는 접근할 수 없었을 뿐입니다. Grimoire는 이것들을 설치 가능한 형태로 만듭니다.

📦 의존성 선언하기 (Declaring dependencies)

# grimoire.toml — 이 파일을 리포지토리(repo)에 커밋하세요
[package]
name    = "my-project"
...

어떤 git 리포지토리(repo)든 유효한 패키지 (package)가 될 수 있습니다. 회사의 내부 엔지니어링 표준, 핀테크 특화 라이브러리, 특정 관할 구역의 법률 관행 세트 — 이 모든 것들이 동일하게 설치됩니다. 버전은 grimoire.lock에 고정됩니다 (네, 여러분이 생각하는 바로 그것입니다).

✍️ 자신만의 스킬 게시하기

무언가를 마스터하기 위해 수년을 보냈다면, 당신의 실천 노하우는 이곳에 속합니다.

# 스킬 파일 검증하기
grimoire validate

...

1. 스킬 마크다운 (markdown) 파일 작성 (이름, 태그, 설명, 출처, 단계)
2. 아무 git 리포지토리(repo)에나 푸시 (push)
3. 다른 사용자는 grimoire install yourgithub/yourpackage로 설치

명명 규칙 (Naming convention): yourorg/grimoire-fintech, yourorg/grimoire-legal-us, yourorg/grimoire-medical. 프라이빗 리포지토리 (Private repos)도 문제없이 작동하며, 설치 방식은 동일합니다.

🏁 직접 시도해보세요

curl -fsSL https://raw.githubusercontent.com/jeffreytse/grimoire/main/scripts/install.sh | bash
grimoire wizard
grimoire check

• GitHub: https://github.com/jeffreytse/grimoire ⭐
• Skills library: https://github.com/jeffreytse/grimoire-core
• Website: https://grimoire.jeffreytse.net

이 프로젝트는 무료이며, 오픈 소스 (MIT)입니다. 위저드 (wizard)를 사용하면 약 2분 만에 첫 번째 컴플라이언스 (compliance) 체크를 수행할 수 있습니다.

궁금합니다. 여러분의 팀은 현재 시스템 프롬프트 (system prompts)나 수동 체크리스트를 통해 어떤 관행을 강제하고 있나요? 그것이 바로 grimoire 스킬이 되어야 할 바로 그런 것들입니다.

댓글을 남기거나 이슈 (issue)를 생성해 주세요 — 특히 여러분의 도메인에서 스킬을 기여하고 싶다면 더욱 환영합니다. 👇