Skip to content

refactor: restructure CLAUDE.md with progressive disclosure pattern#1

Open
twjeffery wants to merge 1 commit intoalphafrom
claude/review-claude-md-bTBgz
Open

refactor: restructure CLAUDE.md with progressive disclosure pattern#1
twjeffery wants to merge 1 commit intoalphafrom
claude/review-claude-md-bTBgz

Conversation

@twjeffery
Copy link
Owner

Restructured the AI assistant documentation following best practices from
https://www.hlyr.dev/blog/writing-a-good-claude-md to improve effectiveness
and maintainability.

Key changes:

  • Reduced CLAUDE.md from 375 lines to 87 lines (77% reduction)
  • Kept only universally applicable architectural knowledge in CLAUDE.md
  • Created agent_docs/ directory for task-specific detailed documentation
  • Organized content into 6 focused documents:
    • component_workflows.md - Step-by-step component development
    • pr_testing_guide.md - PR playground usage and best practices
    • testing.md - Testing commands, frameworks, and strategies
    • naming_conventions.md - Comprehensive naming standards
    • common_issues.md - Troubleshooting guide
    • folder_structure.md - Complete directory reference

Benefits:

  • Better signal-to-noise ratio for AI assistant
  • Progressive disclosure allows reading detailed docs when needed
  • Reduced instruction count improves overall instruction-following
  • More maintainable and searchable documentation
  • All original content preserved, just reorganized

The new structure ensures Claude sees critical architectural patterns
(wrapper pattern, Svelte as source of truth, design tokens first) in
every conversation while keeping task-specific details available on-demand.

Restructured the AI assistant documentation following best practices from
https://www.hlyr.dev/blog/writing-a-good-claude-md to improve effectiveness
and maintainability.

Key changes:
- Reduced CLAUDE.md from 375 lines to 87 lines (77% reduction)
- Kept only universally applicable architectural knowledge in CLAUDE.md
- Created agent_docs/ directory for task-specific detailed documentation
- Organized content into 6 focused documents:
  * component_workflows.md - Step-by-step component development
  * pr_testing_guide.md - PR playground usage and best practices
  * testing.md - Testing commands, frameworks, and strategies
  * naming_conventions.md - Comprehensive naming standards
  * common_issues.md - Troubleshooting guide
  * folder_structure.md - Complete directory reference

Benefits:
- Better signal-to-noise ratio for AI assistant
- Progressive disclosure allows reading detailed docs when needed
- Reduced instruction count improves overall instruction-following
- More maintainable and searchable documentation
- All original content preserved, just reorganized

The new structure ensures Claude sees critical architectural patterns
(wrapper pattern, Svelte as source of truth, design tokens first) in
every conversation while keeping task-specific details available on-demand.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants