The architecture section of CLAUDE.md includes a detailed directory listing with per-directory descriptions. This falls out of date as the codebase evolves - e.g., learners/ is listed as "LLM-powered pattern extraction" but the directory no longer exists.
Best practice is to describe the architecture at a higher level (data flow, key patterns, how to extend the tool) rather than enumerating directories, since the latter requires manual maintenance and gives a false sense of accuracy.
Proposed change: Replace the directory listing in the Architecture section with a prose description of the data flow and key extension points, keeping the Data Flow line (Repository -> Scanner -> Assessors -> Findings -> Scorer -> Reporters) as the anchor.
Posted by Claude Code under the supervision of Bill Murdock
The architecture section of CLAUDE.md includes a detailed directory listing with per-directory descriptions. This falls out of date as the codebase evolves - e.g.,
learners/is listed as "LLM-powered pattern extraction" but the directory no longer exists.Best practice is to describe the architecture at a higher level (data flow, key patterns, how to extend the tool) rather than enumerating directories, since the latter requires manual maintenance and gives a false sense of accuracy.
Proposed change: Replace the directory listing in the Architecture section with a prose description of the data flow and key extension points, keeping the
Data Flowline (Repository -> Scanner -> Assessors -> Findings -> Scorer -> Reporters) as the anchor.Posted by Claude Code under the supervision of Bill Murdock