refactor: implement comprehensive documentation framework #46
Conversation
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
Add git worktree directory to gitignore to prevent tracking of development worktrees used for isolated feature development. Update CLAUDE.md to reduce cognitive overload: - Add Git Worktrees section with clear .workbench usage patterns - Consolidate duplicate deployment and framework information - Remove redundant Framework Stack and Component Architecture sections - Reorganize structure for better flow and reduced duplication - Reduce file size while maintaining all essential information
Massive context optimization and documentation reorganization: CLAUDE.md Optimization (233 → 62 lines): - Strip down to critical overrides and behavioral rules only - Keep essential deployment and architectural principles - Add project identification and documentation references - Achieve ~75% reduction in initial context load New Documentation Structure: - .claude/docs/project-architecture.md - Framework stack, structure, utilities - .claude/docs/development-workflow.md - Git worktrees, commands, processes - .claude/docs/fork-risk-monitoring.md - Complete system architecture - .claude/docs/component-patterns.md - Component architecture, state patterns Benefits: - Reduced startup context by ~80% - Better separation of concerns - Discoverable, precise documentation - Maintains all essential knowledge while improving efficiency
Improve separation of concerns: - Move dev server and worktree rules to development-workflow.md - Keep only fundamental behavioral overrides in CLAUDE.md - Further reduce CLAUDE.md to absolute essentials CLAUDE.md now contains only: - Core architectural principles (state management separation) - Multi-agent coordination patterns - Critical deployment architecture rules Result: Even more focused bootstrap file with better organization
Transform documentation from inventory to principles: New File: - styling-patterns.md - CSS utilities, Tailwind patterns, custom effects (fx-glow, etc.) Refined Files: - project-architecture.md - Now focuses on organizational principles vs file listings - component-patterns.md - Removed specific file listings, added discovery patterns - development-workflow.md - Added styling patterns reference and git discovery tips - CLAUDE.md - Updated to reference new styling documentation Key Improvements: - Architecture defines WHERE files should go (principles) - Use git ls-files for WHAT files exist (discovery) - Better separation: principles vs implementation vs inventory - More maintainable (no updates needed when files change) - Clearer purpose for each documentation file
Transform from instructional guidelines back to descriptive architecture: Key Improvements: - Restore visual tree structure for immediate clarity - Add nested component organization (Fork* component hierarchy) - Include CI/CD pipeline architecture (GitHub Actions workflow) - Show data flow patterns (Provider → Context → Components) - Describe what IS rather than what SHOULD BE - Include all architectural elements (.github/, public/, contracts/) Result: - Clear visual representation of project structure - Hierarchical component relationships visible - Complete architectural picture including CI/CD - Reference documentation vs. instructional guidelines
Create clear separation between universal dev practices and feature-specific requirements: New Structure: - .claude/docs/prd/ directory for Product Requirements Documents - Move fork-risk-monitoring.md → prd/fork-risk-monitoring.md Documentation Cleanup: - Remove feature-specific testing from development-guidelines.md - Focus on universal dev rituals (worktrees, quality gates, commands) - Remove fork-specific deployment verification steps - Keep only universal pre-deployment checks Updated References: - Fix CLAUDE.md file reference: development-workflow.md → development-guidelines.md - Add PRD section to CLAUDE.md for feature-specific documentation - Establish pattern for future feature documentation Benefits: - Universal dev guidelines stay clean and focused - Feature-specific requirements clearly separated - Scalable structure for future features - Reduced cognitive overload for developers
Major reorganization following framework principles: New Structure: - .claude/docs/ - LLM knowledge only (augur-* for local, astro-* for framework) - requirements/ - Human-facing product requirements (prd-*) File Renames: - project-architecture.md → augur-architecture.md - development-guidelines.md → augur-development-guidelines.md - styling-patterns.md → augur-styling-patterns.md - component-patterns.md → augur-component-patterns.md - prd/fork-risk-monitoring.md → requirements/prd-fork-risk-monitoring.md Benefits: - Clear LLM vs human documentation separation - Consistent prefix-based organization (augur-*, astro-*, prd-*) - Flat structure with searchable filenames - Scalable pattern for future framework knowledge - Professional requirements separation Updated all cross-references to maintain consistency.
- Convert augur-styling-patterns.md to augur-styling-guidelines.md - Focus on design system strategy vs utility listings - Remove duplicate content and behavioral constraints - Refine component patterns to project-specific patterns - Update CLAUDE.md reference to reflect new strategic focus
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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
Implements a comprehensive documentation framework that significantly reduces CLAUDE.md context pollution while establishing clear separation of concerns between LLM knowledge and human-facing documentation.
Key achievements:
Changes Made
Documentation Architecture
augur-*for project knowledge,astro-*for framework knowledgerequirements/directory for human-facing specsFile Structure
Content Refinements
Test Plan
Breaking Changes
None - this is purely a documentation reorganization that improves maintainability and reduces cognitive overhead.