deadrule 0.2.1 → 0.3.0

package/README.ko.md

@@ -0,0 +1,158 @@
+# deadrule
+
+AI 코딩 어시스턴트 설정에서 죽은 규칙을 찾아줍니다.
+
+AI 코딩 도구(Claude Code, Cursor, Codex)에서 규칙과 스킬을 정의할 수 있습니다. 시간이 지나면 규칙이 쌓입니다. 어떤 건 작업과 전혀 관련이 없고, 어떤 건 서로 중복되고, 어떤 건 AI가 이미 하는 것을 또 지시합니다. **deadrule**이 찾아줍니다.
+
+**[English README](README.md)**
+
+## 데모
+
+![deadrule 데모](demo/demo.gif)
+
+## 바로 시작
+
+```bash
+npx deadrule
+```
+
+API 키 불필요. 설정 불필요. 런타임 의존성 0개.
+
+## 검사 항목
+
+| 검사 | 찾는 것 |
+|------|---------|
+| **죽은 규칙** | 한 번도 쓰지 않는 언어의 규칙 (세션 로그 기반) |
+| **중복 파일** | 서로 겹치는 규칙 파일 |
+| **겹치는 지시사항** | 여러 파일에 복붙된 동일 지시문 |
+| **기본 동작 중복** | Claude가 이미 하는 행동을 또 지시하는 규칙 |
+| **모호한 지시사항** | 너무 추상적이라 실행 불가능한 지시문 |
+| **토큰 비용** | 각 규칙 파일이 소비하는 토큰 수 |
+| **오래된 규칙** | 90일 이상 수정되지 않은 규칙 |
+
+## 죽은 규칙을 찾는 방법
+
+deadrule은 모든 프로젝트의 Claude Code 세션 로그(JSONL)를 읽습니다. 실제로 편집한 파일 확장자(`.ts`, `.py`, `.go` 등)를 추출한 뒤, 규칙과 대조합니다. Python 규칙이 있는데 `.py` 파일을 한 번도 편집하지 않았다면 — 그 규칙은 **죽은 규칙**입니다.
+
+## 커스텀 경로
+
+```bash
+# 특정 디렉토리 스캔
+deadrule ./my-rules/
+
+# 여러 경로 동시 스캔
+deadrule ./rules/ ./agents/
+
+# 클론한 규칙 세트 스캔
+deadrule ~/everything-claude-code/rules/
+```
+
+## 기본 스캔 위치
+
+- `~/.claude/rules/*.md` (글로벌 규칙)
+- `.claude/rules/*.md` (프로젝트 규칙)
+- `CLAUDE.md` (프로젝트 루트)
+- `.cursorrules` (Cursor)
+
+## 실전 테스트: Everything Claude Code (136개 규칙)
+
+```
+$ deadrule ./rules/ ./agents/
+
+deadrule v0.2.1
+================
+
+Scanned: 136 rules (0 global, 136 project)
+Total token cost: ~90,077 tokens (45.0% of context)
+
+DEAD RULES (based on 34 sessions across all projects)
+  Languages you actually use:
+    .js      8 file edits
+    .ts      7 file edits
+    .tsx     7 file edits
+    .html    7 file edits
+    .py      4 file edits
+
+  Rules for languages you NEVER use:
+    cpp/coding-style.md
+    -> No C++ files edited in 34 sessions
+    dart/coding-style.md
+    -> No Dart/Flutter files edited in 34 sessions
+    rust/coding-style.md
+    -> No Rust files edited in 34 sessions
+    ... (총 61개 죽은 규칙)
+
+OVERLAPPING DIRECTIVES (50 found, showing top 5)
+  "Surgical fixes only - don't refactor, just fix the error"
+  -> repeated in: 7 files
+
+  "Approve: No CRITICAL or HIGH issues"
+  -> repeated in: 11 files
+
+REDUNDANT WITH CLAUDE DEFAULTS
+  "SQL injection prevention (parameterized queries)"
+  -> Claude already uses parameterized queries by default
+
+SUMMARY
+  61 DEAD rule(s) - never relevant to your work
+  1 duplicate pair(s)
+  50 overlapping directive(s)
+  13 redundant with Claude defaults
+  25 vague directive(s)
+```
+
+주요 발견:
+- **136개 규칙 중 61개가 죽은 규칙** — 매 세션 로드되지만 한 번도 관련 없음
+- **약 9만 토큰 (컨텍스트의 45%)** 이 규칙에만 소비됨
+
+## GitHub Action
+
+워크플로우에 추가하면 PR마다 자동으로 규칙 건강 상태를 체크합니다:
+
+```yaml
+# .github/workflows/deadrule.yml
+name: Rule Health Check
+on: [pull_request]
+
+jobs:
+  deadrule:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: JSK9999/deadrule@main
+        with:
+          paths: '.claude/rules'
+```
+
+문제가 발견되면 PR에 자동으로 리포트 코멘트가 달립니다.
+
+## CLI 옵션
+
+```bash
+# 기본 스캔
+npx deadrule
+
+# 커스텀 경로 스캔
+npx deadrule ./rules/ ./agents/
+
+# CI/CD용 JSON 출력
+npx deadrule --json
+```
+
+## 로드맵
+
+[이슈 목록](https://github.com/JSK9999/deadrule/issues)에서 계획된 기능을 확인하세요.
+
+- [x] CI/CD용 `--json` 출력
+- [x] GitHub Action + PR 코멘트
+- [ ] `--fix` 중복 규칙 자동 병합
+- [ ] Cursor `.mdc` 및 Codex `AGENTS.md` 지원
+- [ ] 프로젝트 간 규칙 비교
+
+## 기여
+
+[CONTRIBUTING.md](CONTRIBUTING.md)에서 설정 방법과 가이드라인을 확인하세요.
+
+## 라이선스
+
+Apache 2.0

package/README.md

@@ -2,7 +2,13 @@
 
 Find dead rules in your AI coding assistant config.
 
-AI coding tools (Claude Code, Cursor, Codex) let you define rules and skills. Over time, rules pile up. Some duplicate each other. Some repeat what the AI already does. Some are too vague to follow. **deadrule** finds them.
+AI coding tools (Claude Code, Cursor, Codex) let you define rules and skills. Over time, rules pile up. Some are never relevant to your work. Some duplicate each other. Some repeat what the AI already does. **deadrule** finds them.
+
+**[한국어 README](README.ko.md)**
+
+## Demo
+
+![deadrule demo](demo/demo.gif)
 
 ## Quick Start
 
@@ -16,6 +22,7 @@ No API keys. No setup. No runtime dependencies.
 
 | Check | What it finds |
 |-------|--------------|
+| **Dead rules** | Rules for languages you never use (based on session logs) |
 | **Duplicates** | Rules that overlap with each other |
 | **Overlapping directives** | Same instruction copied across multiple files |
 | **Claude defaults** | Rules that repeat Claude's built-in behavior |
@@ -23,12 +30,14 @@ No API keys. No setup. No runtime dependencies.
 | **Token cost** | How many tokens each rule file consumes |
 | **Stale rules** | Rules not modified in 90+ days |
 
-## Custom Paths
+## How it finds dead rules
+
+deadrule reads your Claude Code session logs (JSONL) across all projects. It extracts which file types you actually edit (`.ts`, `.py`, `.go`, etc.), then cross-references with your rules. If you have Python rules but never edited a `.py` file — those rules are **dead**.
 
-Scan any directory of rules:
+## Custom Paths
 
 ```bash
-# Scan a specific rules directory
+# Scan a specific directory
 deadrule ./my-rules/
 
 # Scan multiple paths
@@ -38,7 +47,7 @@ deadrule ./rules/ ./agents/
 deadrule ~/everything-claude-code/rules/
 ```
 
-## Where it scans (default)
+## Default scan locations
 
 - `~/.claude/rules/*.md` (global rules)
 - `.claude/rules/*.md` (project rules)
@@ -50,55 +59,94 @@ deadrule ~/everything-claude-code/rules/
 ```
 $ deadrule ./rules/ ./agents/
 
-deadrule v0.1.0
+deadrule v0.2.1
 ================
 
 Scanned: 136 rules (0 global, 136 project)
 Total token cost: ~90,077 tokens (45.0% of context)
 
-DUPLICATES
-  agents/java-build-resolver.md <-> agents/kotlin-build-resolver.md  (51% overlap)
-
-OVERLAPPING DIRECTIVES (50 found, showing top 10)
+DEAD RULES (based on 34 sessions across all projects)
+  Languages you actually use:
+    .js      8 file edits
+    .ts      7 file edits
+    .tsx     7 file edits
+    .html    7 file edits
+    .py      4 file edits
+
+  Rules for languages you NEVER use:
+    cpp/coding-style.md
+    -> No C++ files edited in 34 sessions
+    dart/coding-style.md
+    -> No Dart/Flutter files edited in 34 sessions
+    rust/coding-style.md
+    -> No Rust files edited in 34 sessions
+    ... (61 dead rules total)
+
+OVERLAPPING DIRECTIVES (50 found, showing top 5)
   "Surgical fixes only - don't refactor, just fix the error"
-  -> repeated in: agents/cpp-build-resolver.md, agents/dart-build-resolver.md,
-     agents/java-build-resolver.md, agents/rust-build-resolver.md,
-     agents/go-build-resolver.md, agents/kotlin-build-resolver.md,
-     agents/pytorch-build-resolver.md
+  -> repeated in: 7 files
 
   "Approve: No CRITICAL or HIGH issues"
-  -> repeated in: common/code-review.md, agents/code-reviewer.md,
-     agents/cpp-reviewer.md, agents/csharp-reviewer.md, ... (11 files)
+  -> repeated in: 11 files
 
 REDUNDANT WITH CLAUDE DEFAULTS
-  common/security.md: "SQL injection prevention (parameterized queries)"
-  -> Claude already uses parameterized queries by default
-
-  java/security.md: "Always use parameterized queries - never concat..."
+  "SQL injection prevention (parameterized queries)"
   -> Claude already uses parameterized queries by default
 
-TOKEN COST BREAKDOWN (top 10)
-  agents/flutter-reviewer.md       ~ 3510 tokens  ||||......  4%
-  agents/performance-optimizer.md  ~ 3111 tokens  |||.......  3%
-  agents/code-reviewer.md          ~ 2187 tokens  ||........  2%
-  ... 126 more files (~69,115 tokens)
-
 SUMMARY
+  61 DEAD rule(s) - never relevant to your work
   1 duplicate pair(s)
   50 overlapping directive(s)
   13 redundant with Claude defaults
   25 vague directive(s)
 ```
 
-Key finding: **ECC loads ~90K tokens (45% of context window) in rules alone.**
+Key findings:
+- **61 out of 136 rules are dead** — loaded every session but never relevant
+- **~90K tokens (45% of context window)** consumed by rules alone
+
+## GitHub Action
+
+Add to your workflow to automatically check rule health on every PR:
+
+```yaml
+# .github/workflows/deadrule.yml
+name: Rule Health Check
+on: [pull_request]
+
+jobs:
+  deadrule:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: JSK9999/deadrule@main
+        with:
+          paths: '.claude/rules'
+```
+
+This will comment on PRs with a rule health report when issues are found.
+
+## CLI Options
+
+```bash
+# Default scan
+npx deadrule
+
+# Scan custom paths
+npx deadrule ./rules/ ./agents/
+
+# JSON output for CI/CD
+npx deadrule --json
+```
 
 ## Roadmap
 
 See [open issues](https://github.com/JSK9999/deadrule/issues) for planned features.
 
-- [ ] Runtime rule tracking via hooks (find truly unused rules)
-- [ ] `--json` output for CI/CD
+- [x] `--json` output for CI/CD
+- [x] GitHub Action with PR comments
 - [ ] `--fix` auto-merge duplicate rules
+- [ ] Cursor `.mdc` and Codex `AGENTS.md` support
 - [ ] Cross-project rule comparison
 
 ## Contributing

package/dist/index.js

@@ -9,8 +9,10 @@ import { analyzeStaleness } from "./analyzers/staleness.js";
 import { analyzeUsage } from "./analyzers/usage.js";
 import { printReport } from "./reporter.js";
 async function main() {
+    const args = process.argv.slice(2);
+    const jsonMode = args.includes("--json");
     const cwd = process.cwd();
-    const customPaths = process.argv.slice(2).filter((a) => !a.startsWith("-"));
+    const customPaths = args.filter((a) => !a.startsWith("-"));
     const scanResults = await scanRuleFiles(cwd, customPaths);
     if (scanResults.length === 0) {
         console.log("No rule files found.");
@@ -44,13 +46,18 @@ async function main() {
             }
             : undefined,
     };
-    printReport(result);
     const issues = duplicates.length +
         directiveOverlaps.length +
         defaultMatches.length +
         vagueDirectives.length +
         staleRules.length +
         (result.usage?.deadRules.length ?? 0);
+    if (jsonMode) {
+        console.log(JSON.stringify({ ...result, issueCount: issues }, null, 2));
+    }
+    else {
+        printReport(result);
+    }
     process.exit(issues > 0 ? 1 : 0);
 }
 main().catch((err) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deadrule",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Find dead rules in your AI coding assistant config",
   "type": "module",
   "bin": {