docs(claude): add project-level CLAUDE.md cognitive anchor#56
Open
juice094 wants to merge 7 commits into
Open
Conversation
Create `.claude/CLAUDE.md` as an anti-amnesia anchor for AI sessions. This file is designed to survive context compression and contains: - Immutable Facts table (version, tests, tools, schema, etc.) - Architecture Guardrails (RF-1 through RF-7) - Current Context (phase, gaps, active work) - Known Architecture Gaps (distinguishing "not yet implemented" from "broken") - Anti-amnesia Checklist for session startup - Quick Reference commands and key file mappings This addresses the systematic information loss problem identified in context-compressed AI long-range work. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
project_context previously returned repo metadata, relations, and workflows but omitted two high-signal fields: unmitigated known limits (risk layer) and available skills. This meant AI callers had to make separate tool calls to assess project health or discover capabilities. - Add known_limits: top 20 unmitigated entries from L3 risk layer - Add skills: top 20 registered skills with type/tags - Update stale tool-count comment: 37 → 68 - Refresh CLAUDE.md gap tracker to reflect completed items Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Stable tier requires "unit-tested" per architecture guardrails. query_repos, vault_search, and vault_read previously lacked dedicated JSON-RPC-level tests, relying only on indirect scenario coverage. This commit adds independent tests for each. - test_tools_call_devkit_query_repos: empty registry + seeded repo - test_tools_call_devkit_vault_search: keyword search with scan - test_tools_call_devkit_vault_read: existing note + not-found error - seed_repo() helper for lightweight entity insertion Total tests: 485 → 488 (3 new) Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
mcp-tools.md was severely outdated: - Tool count said 40, actual is 68 - 4 tools mislabeled Experimental→Beta (code_metrics, module_graph, call_graph, dead_code) - 3 tools mislabeled Stable→Beta (hybrid_search, project_brief) - 1 tool mislabeled Stable→Experimental (session_recall) - Missing categories: Index (3), Workflow (3), Relation (3), KnownLimit (2) - Missing Vault tools: daily, graph, export, history - Missing Session tools: 12 of 13 not listed stable-tools/README.md also listed Beta/Experimental tools as Stable. Deleted incorrect docs (project_brief.md, hybrid_search.md, session_recall.md) and updated README to reflect the actual 5 Stable tools with test coverage. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Centralized record of known issues, test coverage gaps, and architectural debt. Includes 28 tools lacking invocation tests, repo.rs 730-line remainder, vault search linear scan performance, and missing document_convert tool. Resolved items archived with version/commit references. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Add JSON-RPC-level tests for high-frequency Beta tools: - devkit_status: empty registry returns "fresh" overall - devkit_workflow_list: empty registry returns count=0 - devkit_index: empty registry returns indexed=0 These tools are called frequently in real-world usage but previously lacked dedicated test coverage, relying only on indirect exercise. Total tests: 488 → 491 (3 new) Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Add Experimental-tier PDF/PPTX → Markdown conversion tool (pdftotext / python-pptx pipeline). Includes: - devkit_document_convert implementation with quality heuristics - Registration in McpToolEnum (69 tools total) - JSON-RPC invocation tests for 6 key tools (query_repos, vault_search, vault_read, status, workflow_list, index) plus document_convert error path - README/AGENTS/CHANGELOG/KNOWN_ISSUES/mcp-tools.md/CLAUDE.md updates - Cargo fmt pass Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Create
.claude/CLAUDE.mdas an anti-amnesia anchor for AI long-range work.Problem
Context compression in multi-turn AI sessions causes systematic information loss:
Solution
A small, structured anchor file at
.claude/CLAUDE.mdcontaining:Design Principles
🤖 Generated with Claude Code