[FEATURE REQUEST] Optimize CLAUDE.md Imports for Complex Bidirectional Symlink Systems Environment Information

Resolved 💬 5 comments Opened May 10, 2025 by MattSStack Closed Jan 5, 2026

@bcherny

Claude CLI Version: Latest (from context, assumed to be 0.2.9x)
Operating System: macOS (from context)
Integration System: ANFL Rule-Based Compliance System
Directory Structure: Extensive hierarchical structure with bidirectional symlinks

Description
We currently have a complex hierarchical rule system where Claude should reference multiple rule files through bidirectional symlinks. Our system is designed with:

A central claude.md file that references rule files through markdown links
Empty bidirectional symlink directories at:

/10_claude/07_symlinks/claude_to_rules/
/10_claude/07_symlinks/rules_to_claude/

Python utilities (symlink_manager.py) that should populate these symlinks

With the new Claude memory imports feature (using @path/to/import syntax), we need guidance on optimizing this architecture for better Claude integration.
Current Implementation
We have numerous rule categories (25+) with multiple rules in each category, organized as:
/01_infrastructure/40_stow_management/40_anfl_compliance/src/01_global/XXXxxx_category_rules/01_rules/XXX001_rule_name.yaml
For example:
/CORExxx_core_rules/01_rules/CORE001_file_header.yaml
/SECxxx_security_rules/01_rules/SEC001_document_classification.yaml
Our symlink_manager.py was designed to:

Parse claude.md to extract rule references
Create symlinks from Claude's rule references to actual rule files
Create symlinks from rule files back to Claude's documentation
Update claude.md with new rules when needed

Requested Enhancements and Questions
We need guidance on how to effectively use the new @path/to/import syntax within this bidirectional symlink architecture:

Symlink Compatibility: Can Claude memory imports work effectively with symlinks? Should we use direct file paths instead of symlinks in the import statements?
Organization Strategy: What's the most efficient way to organize imports for potentially 50+ rule files while maintaining readability?
Import Hierarchy: Is it better to use a single CLAUDE.md file with all imports, or create multiple files organized by rule category that are imported by a main file?
Performance Considerations: Are there any performance implications when importing a large number of rule files (approximately 50+ files averaging 2KB each)?
Dynamic Management: What patterns would work best for programmatically generating and updating the @path/to/import statements in our Python scripts?

Example Implementation Options
Option 1: Single file with sections
markdown# CLAUDE.md

Core Rules

@/path/to/CORE001_file_header.yaml
@/path/to/CORE002_extractor.yaml

Security Rules

@/path/to/SEC001_document_classification.yaml
Option 2: Multiple files with imports
markdown# CLAUDE.md
@/10_claude/rule_imports/core_rules.md
@/10_claude/rule_imports/security_rules.md
Option 3: Using symlinks
markdown# CLAUDE.md
@/10_claude/07_symlinks/claude_to_rules/CORE001
@/10_claude/07_symlinks/claude_to_rules/SEC001
Additional Context
Our rule system is part of a 9-layer architecture with position-based classification (A, B, C positions). This ensures high-quality implementation of mission-critical components. The bidirectional symlinks are designed to maintain navigability and discoverability throughout this complex system.
Since rebuilding the symlinks is a simple process with our existing tools, we're primarily interested in understanding the optimal pattern for leveraging Claude's memory imports with our architecture.

View original on GitHub ↗

This issue has 5 comments on GitHub. Read the full discussion on GitHub ↗