ai-ready

AI 에이전트가 일하기 좋은 저장소를 만들고 유지하는 Claude Code 플러그인입니다.

기준은 하나입니다. 강제할 수 있는 규칙은 lint·타입·테스트·CI·hook 으로 잡고, 문서에는 강제할 수 없는 것(왜·의도· 어디에 무엇이 있나)만 남깁니다. 에이전트는 문서를 읽고도 규칙을 놓칠 수 있지만, CI 에서 실패하는 lint 규칙은 놓칠 수 없습니다. 그래서 규칙이 문서에만 있으면 먼저 도구로 옮길 수 있는지 따지고, 옮길 수 없는 것만 이유와 함께 문서에 둡니다.

설치

1. 마켓플레이스 등록

/plugin marketplace add kunsanglee/ai-ready

2. 플러그인 설치

/plugin install ai-ready@ai-ready

3. 업데이트

/plugin marketplace update ai-ready

설치 확인

/plugin list

Claude Code 는 plugin.json 의 version 필드가 바뀐 경우에만 새 버전으로 인지합니다. 이 저장소는 매 릴리스에 버전을 올립니다. 설치된 버전은 /plugin list 로, 최신 버전은 CHANGELOG.md 첫 항목으로 확인합니다.

1.x 에서 올라올 때

2.0.0 은 무인 검증 loop(spec·build·review)와 7개 영역 점수를 없앴습니다. 1.x 가 대상 저장소에 깔아 둔 freshness hook 과 .ai-ready/ 설정이 남아 있으면 없는 스크립트를 가리키게 됩니다. 옮기는 순서는 CHANGELOG.md 의 2.0.0 항목에 있습니다.

요구사항

로컬 셸, git, python3 만 있으면 됩니다. 스크립트는 표준 라이브러리만 씁니다. 외부 서비스 인증은 필요 없습니다. PR 코멘트를 읽을 때만 GitHub CLI(gh)를 쓰고, 없으면 코멘트를 붙여 넣으면 됩니다.

쓰는 순서

ai-ready:apply (보고서가 없거나 오래됐으면 audit 부터)  →  (작업)  →  ai-ready:lessons

점검만 하고 소스는 건드리고 싶지 않으면 ai-ready:audit 을 따로 부릅니다.

ai-ready:audit — 빈틈 보고서

스크립트가 사실을 모으고, 모델이 규칙을 나눕니다. 대상 저장소의 .ai-ready/ 아래 파일만 씁니다.

• .ai-ready/gaps.md (스크립트) — 머리에 어느 커밋을 봤는지 적는 기준 줄이 있고, 사실 세 절이 이어집니다
  1. 문서 존재 — 루트·모듈별 AGENTS.md·CLAUDE.md(길이 과다 표시)와 둘의 구조, git 이 무시하는 생성 대상 경로(git check-ignore), docs/design 의 결정 기록 쌍과 union merge 설정, 검증 문서, verify.sh, 이 clone 의 pre-push hook, 안티패턴 원장. 옛 구조(CLAUDE.md 원본 + AGENTS.md 심볼릭 링크)는 전환 제안으로만 적고 바꾸지 않습니다
  2. 강제 수단 — 감지된 lint·formatter·타입체커·테스트 러너·아키텍처 테스트·pre-commit·CI 설정, 그리고 CI 설정 안에서 그 검사를 실제로 부르는 줄. CI·Dockerfile 에서 테스트를 빼거나(-x test, -DskipTests) 실패를 삼키는(|| true, continue-on-error) 줄
  3. 규칙 문장 — 문서에서 "금지·반드시·must·never" 같은 줄을 파일:줄 로
• .ai-ready/audit-report.md (모델) — 규칙 줄마다 넷 중 하나로 나누고 코드·설정에서 근거를 찾아 적습니다.
• .ai-ready/audit-report.prev.md (스크립트) — apply 가 준비 단계에서 보고서를 다시 만들기 직전의 audit-report.md

점수는 매기지 않습니다. 문서 개수로 준비 상태를 말하면, 강제되지 않는 문서를 더 쓰는 쪽으로 기울기 때문입니다.

ai-ready:apply — 승인한 것만

apply 만 불러도 됩니다. 시작할 때 audit.py --check-fresh 로 .ai-ready/ 의 두 보고서가 지금 커밋과 맞는지 봅니다. 보고서가 없거나, 다른 커밋에서 만들었거나, 커밋하지 않은 변경(추적하지 않는 새 파일 포함, .gitignore 로 무시되는 파일 제외)이 있으면 audit 을 먼저 돌려 보고서를 새로 만든 뒤 이어 갑니다. 보고서만 커밋한 경우는 같은 기준으로 봅니다. 보고서 머리의 기준 줄(- 기준: 커밋 <해시>)로 판정하므로, 이 줄이 없는 2.2.0 앞의 보고서도 다시 만듭니다. 다시 만들 때 옛 audit-report.md 는 .ai-ready/audit-report.prev.md 로 옮겨 둡니다(그 전의 것은 덮습니다). 적용한 항목이 있으면 마무리에서 gaps.md 에 "이 보고서로 이미 apply 했다" 는 표시 줄을 남깁니다. 다음 apply 는 이 줄을 보고 적용 전 분류를 쓰지 않고 보고서를 새로 만듭니다. 마무리는 audit-report.md 를 옮기지 않으므로, .prev 에는 다시 만들기 직전의 보고서가 다음에 다시 만들 때까지 남습니다.

대화형 실행에서 지금 커밋하지 않은 변경이 있으면(보고서가 없을 때도. 커밋이 하나도 없는 저장소에서는 변경을 확인하지 않습니다) 보고서를 다시 만들기 전에 그 상태로 계속할지 먼저 묻고, 먼저 커밋하겠다고 하면 멈춥니다. 비대화 실행은 묻지 않고 계속하며, 마무리 보고 첫 줄에 커밋하지 않은 변경이 있는 트리에서 적용했다고 적습니다.

서명이 없는(사람이 관리하는) 파일과, 서명을 남긴 채 고친 초안은 덮어쓰지 않습니다. 초안의 서명 줄에는 본문 해시가 들어 있어 고쳤는지 알 수 있습니다. 그런 파일이 있으면 스크립트가 아무것도 쓰지 않고 멈추고, 그 파일은 필요한 부분만 고친 diff 로 제안합니다. 초안을 다시 만들고 싶으면 파일을 지우고 돌립니다. 만들 원본 파일(AGENTS.md·docs/· scripts/)이 git 에서 무시되거나 심볼릭 링크일 때도 아무것도 쓰지 않고 멈춥니다. 무시되는 것이 @AGENTS.md 한 줄짜리 CLAUDE.md 뿐이면 그 파일만 건너뜁니다.

AGENTS.md 를 원본으로 두고 CLAUDE.md 에서 가져오는 까닭은 Claude Code 문서에 있습니다. 한 폴더에 둘이 있으면 Claude Code 는 CLAUDE.md 만 읽고, @AGENTS.md 가져오기를 권하며, 가져오기 경로는 가져오는 파일 기준으로 풉니다. 심볼릭 링크는 Windows 클론과 Edit·Write 도구에서 제약이 있어 쓰지 않습니다.

ai-ready:lessons — 교훈을 강제 수단이나 문서로

/lessons           # 이 세션에서 사람이 바로잡은 것으로
/lessons 123       # PR #123 의 리뷰 코멘트도 함께

lesson-synthesizer 에이전트(읽기 전용)가 후보마다 먼저 도구로 막을 수 있는지 따져 강제 초안을 내고, 안 되면 이유를 붙인 안티패턴 원장 항목을, 설계 결정이면 결정 카드를 냅니다. 스킬이 후보를 하나씩 보여 주고 승인받은 것만 반영합니다.

강제 수단을 고르는 순서

1. 잘못된 상태를 타입·구조로 표현할 수 없게 만든다.
2. CI 에서 실패하는 lint·금지 API 규칙.
3. 정석 헬퍼(옳은 길을 함수 하나로 만들고, 다른 길은 2번으로 막는다).
4. 런타임 검사.
5. 테스트.
6. 마지막으로 문서.

모듈을 어떻게 정하나

루트가 아닌 디렉토리에 빌드 매니페스트(build.gradle(.kts)·pom.xml·package.json·Cargo.toml·go.mod· pyproject.toml·setup.py)가 있으면 그 디렉토리들이 모듈입니다. 루트에만 있으면 스택 어댑터가 찾은 소스 기준점의 직속 하위 디렉토리가 모듈입니다.

저장소 구조

.
├── .claude-plugin/marketplace.json
├── plugins/ai-ready/                     # Claude Code 플러그인
│   ├── .claude-plugin/plugin.json
│   ├── skills/
│   │   ├── audit/                        # 빈틈 보고서 + 공용 스크립트
│   │   │   └── scripts/
│   │   │       ├── audit.py              # gaps.md
│   │   │       ├── stacks.py             # 모듈 기준점 · 확인 명령 추론
│   │   │       ├── scaffold.py           # 모듈 AGENTS.md 초안 + 가져오는 CLAUDE.md
│   │   │       ├── bootstrap.py          # 루트 문서 · 결정 기록 · 원장 · 검증 문서 초안
│   │   │       ├── install_verify_hook.py  # 대상 clone 에 pre-push hook 설치
│   │   │       ├── managed_doc.py        # 사람이 관리하는 파일을 덮지 않는 규칙
│   │   │       └── project/              # 대상 저장소로 복사되는 verify.sh · check_docs.py,
│   │   │                                 # 대상 clone 의 .git/hooks 에 설치되는 pre-push
│   │   ├── apply/                        # + references/enforcement-drafts.md
│   │   └── lessons/
│   ├── agents/lesson-synthesizer.md
│   └── tests/                            # stdlib unittest
└── build/drift-test.sh                   # 매니페스트 버전·변경 이력·셸 함정 검사

시험은 plugins/ai-ready 에서 python3 -m unittest discover -s tests -t ., 그리고 저장소 루트에서 bash build/drift-test.sh 입니다.

실제 세션으로 확인할 때는 대상 저장소를 ~/.claude 밖 경로(예: /tmp/ai-ready-e2e/)에 복사해 두고 claude -p --plugin-dir <이 저장소>/plugins/ai-ready ... 로 돌립니다. ~/.claude 아래에서 돌리면 권한 검사가 그 경로의 쓰기를 따로 막아 결과가 실제 사용과 달라집니다.

릴리스마다 무엇이 왜 바뀌었는지는 CHANGELOG.md 에 있습니다.

라이선스

MIT

{
  "name": "ai-ready",
  "owner": {
    "name": "kunsanglee"
  },
  "metadata": {
    "description": "Standalone Claude Code marketplace hosting the ai-ready plugin: a score-free gap report on guidance docs and enforcement for AI-agent work, reviewed drafts that move documented rules into lint, tests, CI and hooks, and lessons drafted from session and PR corrections. Release history lives in CHANGELOG.md.",
    "version": "2.2.0"
  },
  "plugins": [
    {
      "name": "ai-ready",
      "source": "./plugins/ai-ready",
      "description": "Keep a repository ready for AI-agent work by enforcing what can be enforced and documenting only what cannot. audit writes a score-free gap report: which guidance docs exist (root and module AGENTS.md and the CLAUDE.md that imports it, docs/design decision records, a verification doc), which lint/typecheck/test/architecture checks exist and whether CI actually runs them, and every documented rule sorted into already enforced, cheap to enforce, not enforceable, or out of date. apply creates only what you approve: a short root AGENTS.md with a one-line CLAUDE.md that imports it (@AGENTS.md), module docs, decision-record pairs with union merge, an anti-pattern ledger, scripts/verify.sh with a git pre-push hook, a docs consistency check, and lint or architecture-test drafts for rules that only lived in prose. lessons turns corrections from the session and PR review into the same kinds of drafts. Release history lives in CHANGELOG.md.",
      "version": "2.2.0",
      "author": {
        "name": "kunsanglee"
      },
      "homepage": "https://github.com/kunsanglee/ai-ready",
      "repository": "https://github.com/kunsanglee/ai-ready",
      "keywords": [
        "ai-readiness",
        "claude-code",
        "audit",
        "documentation",
        "CLAUDE.md",
        "AGENTS.md",
        "enforcement",
        "lint",
        "architecture-tests",
        "decision-records",
        "verification",
        "AI 준비도",
        "강제 수단"
      ],
      "category": "workflow"
    }
  ]
}