CLAUDE.md · git:20260930.bcf8dbd · 2026-09-30 · sha256 e80f8f2665ee0829
CLAUDE.md git:20260930.bcf8dbdA
Immutable. This exact content never changes and is served at /api/v1/blob/e80f8f2665ee0829.
# Logic-Lens — Developer Guide (Claude Code)
This file contains instructions for Claude when working on the Logic-Lens repository itself.
## Project Layout
```
logic-lens/
├── skills/
│ ├── _shared/
│ │ ├── common.md ← Language rule, Iron Law, Logic Score, yaml schema
│ │ ├── logic-risks.md ← L1–L9 risk taxonomy definitions
│ │ ├── semiformal-guide.md ← Execution tracing methodology + min thresholds
│ │ ├── semiformal-checklist.md ← Premises Construction Checklist (single source)
│ │ └── report-template.md ← Report Template (English + Chinese, single source)
│ ├── logic-{review,explain,diff,locate,health}/
│ │ ├── SKILL.md ← Frontmatter + process skeleton (triggers the skill)
│ │ └── *-guide.md ← Detailed step-by-step instructions (loaded on demand)
│ └── logic-fix-all/ ← Skill 6: orchestrates the other five into one pipeline
│ ├── SKILL.md
│ ├── logic-fix-all-guide.md ← Navigation + shared context
│ ├── guide-phases-0-2-consent-scope-health.md
│ ├── guide-phases-3-5-review-locate-clarify.md
│ └── guide-phases-6-9-fix-iterate-report.md
├── .claude-plugin/ ← Claude Code plugin metadata
├── .codex-plugin/ ← Codex CLI plugin metadata
├── gemini-extension.json ← Gemini CLI extension metadata
├── commands/ ← Short command wrappers installed by session-start hook
├── hooks/
│ ├── hooks.json ← Claude Code hook registration (uses ${CLAUDE_PLUGIN_ROOT} — portable across platforms)
│ └── session-start ← Copies commands/ to ~/.claude/commands/ on session start
├── evals/
│ ├── content/v2/evals-v2.json ← Content benchmark test cases (104, current)
│ ├── trigger/v2/ ← Trigger benchmark suites (per skill) — see Gotchas before relying on scores
│ ├── real-world/ ← Real-code probes: second verification line, incl. decoy probes
│ └── v1/ ← Legacy v1 cases (archived for reference)
├── benchmarks/
│ ├── index.json ← Catalog of published runs
│ ├── reports/ ← Human-readable markdown reports per version tag
│ └── runs/ ← Frozen run summaries (workflow: see `benchmarks/README.md`)
├── scripts/ ← Shell scripts invoked by `npm run ...` (validate, lint-shell, trigger-evals, content-evals, grader)
├── tests/ ← Python unit tests (currently `test_grader.py` for the eval grader)
├── docs/ ← Auxiliary docs (model compatibility, research references, case studies, marketing assets)
├── .claude/ ← Repo-local dev harness (see "Harness" below)
│ ├── agents/ ← eval-failure-analyzer, skill-editor, iteration-guard
│ └── skills/ ← iterate-skill, sync-skill-cache, run-iteration-eval, bump-version, new-skill
├── skills-workspace/ ← Scratch space for in-progress skill iterations and benchmark probes (gitignored)
├── CONTRIBUTING.md ← Contribution ground rules and versioning policy
└── AGENTS.md / GEMINI.md ← Companion guides for Codex and Gemini CLI users
```
## Conventions
### SKILL.md Structure
- YAML frontmatter: `name` and `description` are required.
- `description` must include a "Do NOT trigger for:" clause.
- `description` should be explicit about trigger phrases — err on the side of triggering.
- Process section: 5–7 numbered items; each item cites a step in the guide file.
- Setup section: follow lazy loading from `skills/_shared/common.md` §13. Read only the relevant `common.md` sections and the active guide step upfront; load `logic-risks.md`, `semiformal-guide.md`, `semiformal-checklist.md`, `report-template.md`, and later guide sections on demand. Document any required eager read explicitly.
### Guide Files
- Numbered steps (Step 1, Step 2, ...).
- Each step explains the *why*, not just the *what*.
- Sub-steps use letters (Step 2a, 2b).
- Concrete examples preferred over abstract descriptions.
### Risk Codes
- Built-in: L1–L9 (defined in `skills/_shared/logic-risks.md`)
- Custom project-specific: C1, C2, ... (defined in `.logic-lens.yaml` at the repo root — optional file, omit if no custom codes needed)
- Every finding must be tagged with a risk code.
`.logic-lens.yaml` schema: see `skills/_shared/common.md` — `custom_risks` is a list of records with `code`, `name`, `description`, and `severity` fields.
### Version Sync
`package.json` is the source of truth for the version number. Use the script — it rewrites all
six places at once and then runs `validate-repo.sh` to confirm:
```bash
npm run bump-version -- 0.7.0
```
The six places it touches: `package.json`, `.claude-plugin/plugin.json`,
`.claude-plugin/marketplace.json`, `.codex-plugin/plugin.json`, `gemini-extension.json`, and the
`README.md` version badge. `CHANGELOG.md` is **not** touched — add the release entry by hand.
### Iron Law
See `skills/_shared/common.md` — Iron Law section. That is the canonical definition; do not duplicate or paraphrase it here.
## Companion Docs by AI Tool
| File | Read by | Purpose |
|------|---------|---------|
| `AGENTS.md` | OpenAI Codex / Agents SDK | Task instructions for agent-based runners |
| `GEMINI.md` | Gemini CLI | Extension setup and skill invocation for Gemini |
| `CONTRIBUTING.md` | Human contributors | Ground rules, versioning policy, PR requirements |
## Development Commands
Logic-Lens has no runtime npm dependencies; `package.json` only declares script entry points. `npm install` is unnecessary.
```bash
npm run validate # Validate repo structure, JSON integrity, and metadata consistency (scripts/validate-repo.sh)
npm run lint-shell # shellcheck every tracked shell script (scripts/lint-shell.sh)
npm run unit-tests # Run Python unit tests under tests/ (currently grader tests)
npm run trigger-evals # Run trigger-eval suites under evals/trigger/v2/ (scripts/run-trigger-evals.sh)
npm run content-evals # Run evals/content/v2/evals-v2.json end-to-end through claude -p + grade (scripts/run-content-evals.sh) — costs API tokens
npm run bump-version -- 0.7.0 # Sync the version across all six manifests, then validate
```
### 单次迭代评分（不跑完整套件）
```bash
python scripts/grade-iteration.py <iteration-dir>
# 对 skills-workspace/ 下某次迭代打分，无需触发完整 content-evals
# 详见 scripts/README.md 获取参数说明
```
Manual one-liners that don't require the scripts:
```bash
# Verify SKILL.md frontmatter exists in all six skills
grep -l "^name:" skills/*/SKILL.md
# Verify all guide files are present
ls skills/*/logic-*-guide.md
# Verify version is consistent across all metadata files (5 JSON files + README badge)
grep '"version"' package.json .claude-plugin/plugin.json .claude-plugin/marketplace.json .codex-plugin/plugin.json gemini-extension.json
grep -E 'version-[0-9]' README.md
```
## Gotchas
- **`npm run trigger-evals` recall is always 0% for Logic-Lens.** The suite delegates to skill-creator's `run_loop.py`, which asks a model (`claude -p`) whether a query *should* trigger a skill — but Logic-Lens skills are dispatched by Claude Code's IDE plugin mechanism, not by model decision, so every positive case scores 0. The suite is still useful for catching `description` regressions on negative (near-miss) cases; verify real triggers by hand in an interactive Claude Code session. (详细参数说明见 `scripts/README.md`)
- **`skills-workspace/` 目录结构约定：** 每次迭代建子目录（如 `iteration-a25b6c7/`），完成后在目录内放 `FINAL-REPORT.md`。草稿文件不要散放在根级别。根目录下现有少量历史遗留文件（`COMPARISON.md`、`FINAL-REPORT.md` 等）仅供参考，新工作请严格使用子目录。
## First Clone Setup
`hooks/hooks.json` uses the `${CLAUDE_PLUGIN_ROOT}` placeholder, so no path edit is needed regardless of where the repo lives.
**1. Run the session-start hook once manually** to install short-form command wrappers (the hook fires automatically on every session start once Claude Code picks the plugin up, but the first install needs a one-shot kick):
```bash
# Run from the repo root (macOS / Linux / WSL / Git Bash on Windows):
bash hooks/session-start
```
**2. Verify commands are installed:**
```bash
ls ~/.claude/commands/logic-*.md
# Expected: logic-diff.md logic-explain.md logic-fix-all.md logic-health.md logic-locate.md logic-review.md
```
**Platform note:** the hook requires `bash`. On macOS and Linux it is preinstalled. On Windows, Claude Code itself runs under WSL or Git Bash, both of which provide `bash` — no extra install needed. For users installing through the marketplace (`/plugin install`), Claude Code auto-discovers `hooks/hooks.json` and runs the hook on every session — this manual step is only for clone-based development of the plugin itself.
## Adding a New Skill
1. Create `skills/logic-newskill/SKILL.md` following the existing SKILL.md pattern.
2. Create `skills/logic-newskill/logic-newskill-guide.md`.
3. Add a command wrapper to `commands/logic-newskill.md`.
4. No change needed in `gemini-extension.json` — Gemini CLI discovers skills from the `skills/` directory automatically.
5. No change needed in `.codex-plugin/plugin.json` — it points at `skills/` directory and auto-discovers subfolders.
6. Add the skill name to the `for skill in ...` loop in `hooks/session-start`:
```bash
grep -n "for skill in" hooks/session-start
```
7. Add 3–5 eval cases to `evals/content/v2/evals-v2.json` (non-explain cases need `expects_defect` — see CONTRIBUTING.md "Eval Cases"; the unit tests enforce it). Optionally add trigger cases to `evals/trigger/v2/trigger-evals-{skill}.json` — but see Gotchas: positive trigger cases always score 0% for Logic-Lens; trigger evals are only useful for catching `description` regressions on negative cases.
## Harness：Logic-Lens Skill 迭代闭环
**目标:** 把"改 SKILL.md → 同步缓存 → 跑 eval → 诊断 → 验证净收益"的迭代闭环固化为可复用的 agent 团队，避免每次手动踩坑（尤其缓存同步）。
**触发:** 想**提升某个 logic-* skill 的 eval 分数 / 修复失败的 eval 模式**时，使用 `iterate-skill` 编排技能（它会按需调度 `eval-failure-analyzer` / `skill-editor` / `iteration-guard` 三个 agent 与 `sync-skill-cache` / `run-iteration-eval` 两个支撑技能）。单次提问、发版（用 `bump-version`）、新建 skill（用 `new-skill`）不触发本闭环。改完任何 `skills/**` 后跑 eval 前，**必须**先经 `sync-skill-cache` 同步缓存。
**组件位置:** agent 在 `.claude/agents/`，支撑技能在 `.claude/skills/`。
**变更历史:**
| 日期 | 变更内容 | 对象 | 原因 |
|------|----------|------|------|
| 2026-06-01 | 初始构成：迭代闭环 harness（编排技能 iterate-skill + skill-editor/iteration-guard 两个新 agent + sync-skill-cache/run-iteration-eval 两个支撑技能；复用已有 eval-failure-analyzer/bump-version/new-skill） | 全体 | 把 skill 迭代主线工作固化为 agent 团队 |