comment-checker: Instructions file for Claude Code

AGENTS.md

A high-quality, mutation-tested Rust implementation of a Claude Code PostToolUse hook that classifies code comments as justified or unnecessary. SOTA engineering: 100% mutation on the core classifier, property-based tests, constitution-aligned, distributed via GitHub Releases and this repository's Nix flake.

The JS launcher layer uses Effect v4. Never install, import, or pin effect@3.* in the JS side.

Directory map

Path	What it holds
crates/	Rust core (comment-checker crate)
npm/packages/comment-checker/	JS/npm wrapper (ESM + Effect v4 launcher for the Rust binary)
tests/	Integration / F1 tests
eval/	Evaluation corpus
.github/workflows/	CI/release (pnpm + cross-platform Rust)

Startup Workflow

Before writing code, unconditionally:

1. Confirm the working directory (pwd) and the active task (user or task list).
2. Read this file — the whole static surface. No other standing reads.
3. Run the verification commands below and confirm a healthy baseline; repair failures before adding new scope.

No eager-read mandates: document reads are situational, triggered by the work, never by startup:

• README.md — when working in a directory you have not worked in before.
• ARCHITECTURE.md — when the task changes a module boundary or data flow.
• Product/requirements docs — when a decision depends on product intent.
• docs/solutions/ — when implementing or debugging in an area with documented past solutions.
• CONCEPTS.md — when orienting to shared domain vocabulary and definitions.

Working Rules

• One task at a time: finish the active task before starting another.
• Verification required: do not claim done without running the verification commands and recording evidence — decisions, bugs, and conventions to the runtime memory system, active work to the task list.
• Stay in scope: do not modify files unrelated to the active task; scope reduction requires explicit user approval.
• Multi-agent: each agent owns a disjoint file set, claims files before editing, never delegates recursively; the root one-shot verification must pass before any agent claims done.
• Git discipline: Master is for releases only and should remain an empty or minimal commit. All work happens on feature branches. Never commit directly to master. Use git checkout -b feature/... for new work. Rebase or merge only via PRs.