feat: discover Claude Code project instructions

CHANGELOG.md

@@ -8,6 +8,7 @@ This project has a published GitHub Release line, but no stable support or API g
 
 ### Added
 
+- Added discovery support for Claude Code project instructions stored at `.claude/CLAUDE.md`.
 - Added CI smoke checks for the installed `agent-rules-kit` console script and a minimal JSON `check` command.
 
 ### Fixed
@@ -21,6 +22,7 @@ This project has a published GitHub Release line, but no stable support or API g
 
 ### Changed
 
+- Clarified README installation, normal CLI usage, development virtual environment requirements, local checks, and next-release audit readiness.
 - Added Ruff linting to local checks and CI by installing project development dependencies before running `./scripts/check.sh`.
 - Synced product strategy and threat model wording with the published `v0.2.0` release line and unreleased post-`v0.2.0` main state.
 - Synced support, security, README, and release-truth documentation after the published `v0.2.0` GitHub Release.

README.md

@@ -37,6 +37,8 @@
   ·
   <a href="#overview">Overview</a>
   ·
+  <a href="#installation">Installation</a>
+  ·
   <a href="#commands">Commands</a>
   ·
   <a href="#governance-findings">Governance Findings</a>
@@ -45,6 +47,8 @@
   ·
   <a href="#quality-gates">Quality Gates</a>
   ·
+  <a href="#development-status">Development Status</a>
+  ·
   <a href="#maintainer-workflow">Maintainer Workflow</a>
   ·
   <a href="#support">Support</a>
@@ -96,6 +100,7 @@ It focuses on files such as:
 
 - `AGENTS.md`
 - `CLAUDE.md`
+- `.claude/CLAUDE.md`
 - `GEMINI.md`
 - `.cursor/rules/*.mdc`
 - `.github/copilot-instructions.md`
@@ -189,13 +194,40 @@ A clean report means only that the implemented checks did not find a supported i
 
 This project is not published to PyPI yet.
 
+### Normal CLI use
+
+Requirements for using the released CLI:
+
+- Python 3.12 or newer;
+- a Python virtual environment;
+- the wheel artifact from the GitHub Release.
+
 Download the wheel from the `v0.2.0` GitHub Release, then install it in a virtual environment:
 
     python -m venv .venv
     .venv/bin/python -m pip install ./agent_rules_kit-0.2.0-py3-none-any.whl
     .venv/bin/agent-rules-kit --version
+    .venv/bin/agent-rules-kit check /path/to/repository --format console
+
+Normal CLI use does not require Ruff or any development dependency.
+
+### Development from source
+
+Requirements for working on the repository and running local checks:
+
+- Python 3.12 or newer;
+- a Python virtual environment;
+- editable install with development dependencies.
+
+Set up a local development environment from the source tree:
+
+    python -m venv .venv
+    .venv/bin/python -m pip install -e '.[dev]'
+    PATH="$PWD/.venv/bin:$PATH" ./scripts/check.sh
 
-The source tree can still be used directly for development:
+The development dependency group installs tools used by local checks, including Ruff. Installing only a system `ruff` binary is not enough for `./scripts/check.sh` if the active Python cannot import the `ruff` module.
+
+The source tree can also be used directly for quick CLI inspection:
 
     PYTHONPATH=src python -m agent_rules_kit.cli --help
 
@@ -205,6 +237,12 @@ The source tree can still be used directly for development:
 
 ### Check a repository
 
+Installed CLI usage:
+
+    .venv/bin/agent-rules-kit check /path/to/repository --format console
+
+Source-tree development usage:
+
     PYTHONPATH=src python -m agent_rules_kit.cli check tests/fixtures/repositories/single-agent
 
 Example console output:
@@ -215,10 +253,22 @@ Example console output:
 
 ### JSON output
 
+Installed CLI usage:
+
+    .venv/bin/agent-rules-kit check /path/to/repository --format json
+
+Source-tree development usage:
+
     PYTHONPATH=src python -m agent_rules_kit.cli check tests/fixtures/repositories/single-agent --format json
 
 ### Markdown output
 
+Installed CLI usage:
+
+    .venv/bin/agent-rules-kit check /path/to/repository --format markdown
+
+Source-tree development usage:
+
     PYTHONPATH=src python -m agent_rules_kit.cli check tests/fixtures/repositories/single-agent --format markdown
 
 ### Init dry-run
@@ -336,7 +386,11 @@ See:
 
 Local verification is handled by:
 
-    ./scripts/check.sh
+    PATH="$PWD/.venv/bin:$PATH" ./scripts/check.sh
+
+Run this after installing development dependencies with:
+
+    .venv/bin/python -m pip install -e '.[dev]'
 
 The local check suite verifies:
 
@@ -381,13 +435,16 @@ Current status:
 - security boundaries documented;
 - threat model documented.
 
-For future releases, verify:
+Before claiming the next patch release or final audit-ready state, verify:
 
-- local checks pass;
+- all intended unreleased fixes for the patch release are merged into `main`;
+- no known release-blocking audit finding remains open;
+- local checks pass from a development virtual environment;
 - CI passes for the release SHA;
 - sdist and wheel build and install from clean temporary environments;
 - release assets can be downloaded, checksum-verified, installed, and smoke-tested;
 - output examples are generated from real commands;
+- README documents normal CLI use, source-tree development use, virtual environment setup, development dependencies, and local checks;
 - README does not claim unsupported maturity;
 - SECURITY.md and CHANGELOG.md are current;
 - private vulnerability reporting is enabled or its absence is clearly documented;

docs/RULES.md

@@ -12,6 +12,7 @@ These rules apply to supported instruction files discovered by `agent-rules-kit`
 
 - `AGENTS.md`;
 - `CLAUDE.md`;
+- `.claude/CLAUDE.md`;
 - `GEMINI.md`;
 - `.cursor/rules/*.mdc`;
 - `.github/copilot-instructions.md`;

src/agent_rules_kit/discovery.py

@@ -76,6 +76,7 @@ def _exact_instruction_paths() -> tuple[tuple[str, InstructionFileKind], ...]:
     return (
         ("AGENTS.md", InstructionFileKind.AGENTS),
         ("CLAUDE.md", InstructionFileKind.CLAUDE),
+        (".claude/CLAUDE.md", InstructionFileKind.CLAUDE),
         ("GEMINI.md", InstructionFileKind.GEMINI),
         (".github/copilot-instructions.md", InstructionFileKind.COPILOT),
     )

tests/fixtures/repositories/claude-dotdir/.claude/CLAUDE.md

@@ -0,0 +1,13 @@
+# CLAUDE.md
+
+## Scope
+
+These project instructions apply to Claude Code when it works in this repository.
+
+## Authority
+
+These Claude-specific instructions should stay consistent with repository-level agent instructions and maintainer requests.
+
+## Secret handling
+
+Do not add secrets, tokens, credentials, API keys, private URLs, or customer data.

tests/test_diagnostic_fixtures.py

@@ -9,6 +9,7 @@
     "empty-repo/.gitkeep",
     "single-agent/AGENTS.md",
     "multi-agent-overlap/AGENTS.md",
+    "claude-dotdir/.claude/CLAUDE.md",
     "multi-agent-overlap/CLAUDE.md",
     "multi-agent-overlap/GEMINI.md",
     "multi-agent-overlap/.cursor/rules/agent-rules.mdc",

tests/test_discovery.py

@@ -53,6 +53,17 @@ def test_multi_agent_repository_discovers_supported_instruction_files(self) -> N
             ),
         )
 
+    def test_claude_dotdir_repository_discovers_project_claude_file(self) -> None:
+        self.assertEqual(
+            discover_instruction_files(FIXTURE_ROOT / "claude-dotdir"),
+            (
+                InstructionFile(
+                    path=".claude/CLAUDE.md",
+                    kind=InstructionFileKind.CLAUDE,
+                ),
+            ),
+        )
+
     def test_discovery_accepts_string_root(self) -> None:
         discovered = discover_instruction_files(str(FIXTURE_ROOT / "single-agent"))