Add section on folder organization as system map - #1
Open
benvinegar wants to merge 3 commits into
Open
Conversation
…mes disambiguate The skill's 'put the context in the symbol, not the folder' rule plus 'one searchable concept per file' was being read as 'folders are useless', producing source roots with dozens of flat files (e.g. modem-dev/cli needed a follow-up PR to organize 67 flat files in src/). - Clarify the module-path bullet: it's about what a name must carry, not an argument against folders. - Add a section on directory structure: group files into domain-named subfolders, split by feature/layer not syntax kind, folders group but still don't disambiguate. - Point the file-splitting bullet at the subsystem folder instead of the source root, and add a checklist item for folder hygiene. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014C4qvBvsHQScHF5idhxk6g
Drop the prescriptive rules (specific layouts, entry-count thresholds, banned folder names) in favor of the general point: group related files into folders so a directory listing reads as a map, with whatever organizing principle fits the codebase. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014C4qvBvsHQScHF5idhxk6g
Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014C4qvBvsHQScHF5idhxk6g
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
2 participants
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.
This PR expands the code discoverability guide with a new section on folder organization principles.
Summary
Added a new section (2) on using folders as a navigational map of the codebase, with supporting clarifications to existing sections. This emphasizes that while folders should group related files logically, the actual context and meaning should still live in symbol names rather than folder paths.
Key changes
Implementation details
The changes maintain consistency with the existing guide's philosophy: discoverability through clear naming and organization. The new section reinforces that folder structure and symbol naming serve complementary but distinct purposes in making code navigable.
https://claude.ai/code/session_014C4qvBvsHQScHF5idhxk6g