1. Summary
Structural changes - creating directories, moving files, renaming modules - affect every file
that imports or references the moved items. A partial move, where the file moves but some
references still point to the old location, is worse than no move at all. A codeorg.md file
scopes the reorganization, states the target structure, and enumerates what categories of
references need updating.
The key discipline: move one item at a time and update all references to it before touching
anything else. Batching moves hides which move broke which reference.
2. codeorg.md Structure
# Code Organization Context
## Goal
What structural change to make.
## Current Structure
Relevant portion of the current directory tree (only what changes).
## Target Structure
What the structure should look like after the change.
## Reference Types to Update
After each move, scan for and update:
- import/use/require statements in source files
- HTML <script src> and <link href> tags
- Config files that reference file paths
- Build files (Cargo.toml, .csproj, Makefile)
- Documentation that names the old path
## Constraints
- Move one item at a time; update all references before the next move
- Prefer git mv over delete + create to preserve history
- Do not change file content during a move - only paths
- Do not rename or restructure beyond the stated goal
3. Safe Sequence for Structural Changes
- State the target structure first. Ask Claude to describe the full
after-state before any files move. Review it against your intent.
- List all references to the first item to move. Every file that will
need updating should be on the list before the move happens.
- Move one item. Confirm it landed correctly.
- Update all references to that item. Check the list from step 2.
- Verify. Build or load the project; confirm no broken references.
- Repeat for the next item.
4. Example Prompts
Preview before any moves:
Read codeorg.md.
Before moving anything, describe the full target directory structure.
Then list every file that will need a path update after each planned move.
Stop after the list so I can review it.
References first, then move:
Read codeorg.md.
List every file that references [current_path/file.js] - including HTML script tags,
import statements, and any config files. Do not move anything yet.
Then, after reviewing:
The reference list looks complete. Move [file.js] to [new_path/file.js] and
update all the references you listed. Stop after that and confirm what changed.
Creating a new directory structure:
Read codeorg.md.
Create these directories under [root]:
[subdir1]/
[subdir2]/
[subdir3]/
Do not move any files yet. Confirm the directories exist, then stop.
Renaming a module and updating all references:
Read codeorg.md.
I want to rename [OldName.js] to [NewName.js] in place (same directory).
List every file that imports or references OldName before renaming.
After I confirm the list, rename the file and update all references.
5. Common Pitfalls
| Pitfall | Prevention |
|---|
| Moving multiple files at once |
State "one at a time" in codeorg.md and in every prompt |
| References missed in HTML or config files |
Name all reference types in codeorg.md; ask Claude to search each type explicitly |
| Content changed during a move |
State "do not change file content during a move" in codeorg.md |
| History lost (delete + create instead of mv) |
Specify "prefer git mv" in codeorg.md for git-tracked repos |
| Verifying with the wrong working directory |
After each move, state the full path when asking Claude to confirm |
6. Case Study: NewSite/Code Organization
This survey was run against the Code/ content track of NewSite before any structural changes
were planned. The directory holds approximately 90 HTML pages, 22 JS files, and 8 CSS files.
The goal was to identify naming inconsistencies, orphaned files, and empty directories so that
any future reorganization starts from a clear picture rather than discovering problems mid-move.
Nothing is changed here.
codeorg.md
# Code Organization Context
## Target
NewSite/Code/ -- static web content track for code tutorials and AI workflows
All HTML pages, and the js/ and css/ subdirectories
## Mode
Read-only analysis. Do not move, rename, or create any files.
Describe the current organization and suggest improvements.
## Survey Questions
1. What naming prefixes are used for HTML files? Count files per group.
Flag any files that don't fit a clear prefix convention.
2. List all subdirectories and their contents. Flag empty or near-empty ones.
3. In js/ and css/, classify each file as page-group-specific or site-wide utility.
Suggest whether a split into subdirectories would help.
4. Are there directory names that conflict with or duplicate each other
(e.g., _template_cpp/ alongside an empty C++/)?
## Constraints
Analysis only. Do not move, rename, or create any files.
Cite file paths for each observation.
State each suggestion as: current state | proposed change | benefit.
Prompt 1 - survey structure
Read codeorg.md.
List all HTML files in Code/ root, all files in Code/js/, and all files in Code/css/.
Group HTML files by naming prefix, count each group, and flag files with no clear group.
Result 1
HTML files by prefix (90 total):
DecCodeStory_* 14 files declarative programming paradigm series
ImpCodeStory_* 14 files imperative programming paradigm series
AIStory_* 13 files AI narrative series
AIBites_* 12 files AI quick-reference series
AIWorkflows_* 11 files AI-assisted development workflows
RepoCode_* 8 files repository code analysis series
CodeStory_* 6 files code fundamentals series
ProjectStory_* 6 files project walkthrough series
No clear group (6 files):
Code/CodeHome.html track landing/navigation page
Code/CodeGlossary.html standalone reference, no series
Code/ExploreCode.html iframe navigator shell; not a content page
Code/ExploreReposCode.html second navigator variant
Code/CodeStory.html looks like a CodeStory_* entry but has no number
Code/ProjectStory.html looks like a ProjectStory_* entry but has no number
js/ (22 files):
Page-group scripts (one per content series):
AIBitesPages.js AIStoryPages.js AIWorkflowsPages.js
CodeBitesPages.js CodeStoryPages.js DecCodeStoryPages.js
ImpCodeStoryPages.js ProjectStoryPages.js RepoCodePages.js
BasicsBitesPages.js BasicsStoryPages.js
Site-wide utilities (no page-group affiliation):
contentElements.js contentMessages.js cookies.js
FigureSizer.js link-nav.js SitePagesForTools.js
ExploreCodeMsg.js exploreMessages.js
BlogsAndHelp.js CodeContent.js CodeViewer.js
css/ (8 files):
Page-group specific:
Styles_Bits.css Styles_BitsContent.css
Explorer.css gridExplorer.css
Site-wide utilities:
content-links.css explorer-links.css FigureSizer.css link-nav.css
Subdirectories (selected):
AI/ AI demo code (populated)
Projects/ project source code (populated)
archive/ 22 deprecated pages (well organized)
documents/ 8 supporting md files
_template_cpp/ 6 C++ page templates
_template_csharp/ 5 C# page templates
_template_python/ 7 Python page templates
_template_rust/ 6 Rust page templates
C++/ empty
Rust/ empty
Basics/ empty
Components/ empty
Prompt 2 - reorganization suggestions
Read codeorg.md.
Based on the survey, identify reorganization opportunities.
State each as: current state | proposed change | benefit.
Do not implement any changes.
Result 2
1. Ambiguous series-index files
Current: Code/CodeStory.html and Code/ProjectStory.html sit alongside
the numbered CodeStory_01_*.html and ProjectStory_01_*.html series.
Proposed: Rename to CodeStory_Index.html and ProjectStory_Index.html.
Benefit: Makes their role (entry point to the series) explicit by naming
convention; removes the false impression that they are unnumbered
series pages. References in ExploreCode.html left-panel nav would
need updating after the rename.
2. Navigator/shell pages mixed with content pages
Current: CodeHome.html, ExploreCode.html, ExploreReposCode.html live in
the same flat directory as 90 content pages, indistinguishable by
name alone.
Proposed: Move to a Code/navigation/ subdirectory, or prefix them
consistently (Nav_CodeHome.html, Nav_ExploreCode.html).
Benefit: New contributors can immediately distinguish infrastructure
pages from content pages. Script src and link href references
in those files would need path updates.
3. Orphan reference page
Current: Code/CodeGlossary.html has no series prefix and no series.
Proposed: Prefix as CodeResources_Glossary.html to signal it is a
standalone resource rather than a series entry.
Benefit: Consistent naming makes it easier to find and less likely to
be mistaken for a missing series page.
4. Empty language directories
Current: C++/, Rust/, Basics/, Components/ directories are empty.
_template_cpp/, _template_rust/ exist separately with content.
Proposed: Either remove the empty directories (if they have no planned use)
or consolidate: move _template_cpp/ content into C++/templates/
and similarly for Rust.
Benefit: Empty directories imply content that doesn't exist, creating
confusion for contributors exploring the layout. Removing them
or populating them resolves the ambiguity.
5. js/ utility files vs. page-group scripts
Current: 22 files in a flat js/ directory: 11 page-group scripts
(AIWorkflowsPages.js, etc.) and 11 utility files (cookies.js, etc.).
The split is already visible from naming but requires reading each
filename to confirm.
Proposed: Move the 11 utility files to js/utils/ or js/shared/.
Benefit: A contributor adding a new content series knows to add their
Pages.js to js/ and leave js/utils/ alone. The split is structural,
not just conventional. All HTML script src tags referencing the
moved files would need updating -- verify with grep before moving.