Documentation & AI Rules: A Dual Approach
Understanding CONA documentation strategy and how we balance human-focused docs with AI-guided rules
Documentation & AI Rules: A Dual Approach
CONA uses a dual approach to maintaining project knowledge and standards:
- Human-Focused Documentation - In the
/docs
directory - AI-Guided Rules - In the
.cursor/rules
directory
This document explains the reasoning, benefits, and implementation of this dual strategy.
The Challenge
Development teams face a perennial challenge: maintaining consistent standards while preserving knowledge. Traditional approaches have included:
- Extensive documentation that developers rarely read
- Code reviews that repeatedly address the same issues
- Tribal knowledge that disappears when team members leave
With the introduction of AI coding assistants, a new challenge emerged: how do we ensure AI understands our unique patterns and standards?
Our Solution: A Dual-Track Approach
Rather than treating documentation as one-size-fits-all, we’ve separated our knowledge management into two distinct but complementary tracks:
Human-Focused Documentation
Documentation in the /docs
directory is:
- Rich with context and explanations
- Enhanced with diagrams and visualizations
- Focused on teaching concepts and “why”
- Organized for discovery and learning
- Designed for comprehensive understanding
AI-Guided Rules
Rules in the .cursor/rules
directory are:
- Concise and technically precise
- Packed with specific implementation patterns
- Focused on the “how” of implementation
- Organized for retrieval and application
- Designed for consistent execution
When to Use Which Approach
Create Human Documentation When:
- Onboarding new team members
- Explaining complex business logic
- Documenting architectural decisions
- Creating step-by-step guides
- Illustrating workflows with diagrams
- Clarifying the reasoning behind patterns
Create AI Rules When:
- Defining coding standards
- Establishing file structure patterns
- Specifying import conventions
- Standardizing component structures
- Defining API interaction patterns
- Establishing testing requirements
Areas Requiring Both
Some critical areas should have both human documentation and AI rules:
Area | Human Documentation | AI Rules |
---|---|---|
Architecture | System diagrams, rationale, evolution | Implementation patterns, file organization |
State Management | Decision framework, conceptual model | Code patterns, specific approaches |
Testing | Strategy, coverage goals, philosophy | Implementation standards, mock patterns |
Performance | Critical paths, benchmarks, goals | Optimization techniques, patterns to avoid |
Implementation Guide
Creating Human Documentation
- Structure: Use MDX with clear headings and sections
- Content: Include context, reasoning, examples, and diagrams
- Location: Place in the appropriate
/docs
subdirectory - Index Entry: Add the document to
docs.json
to make it discoverable - Format: Follow our documentation style guide
- Cross-Reference: Note related AI rules when applicable
Important: All documentation files must be added to
docs.json
to appear in the navigation and be properly indexed for search. Failing to add your document todocs.json
will make it invisible to users.
Creating AI Rules
- Structure: Use MDC with proper metadata headers
- Content: Focus on implementation patterns with code examples
- Location: Place in
.cursor/rules
directory - Format: Follow concise, technically specific language
- Metadata: Include appropriate glob patterns and application settings
Examples
Example 1: State Management
Human Documentation (in /docs/core-concepts/state-management.mdx
):
- Visual diagram of state types
- Decision tree for choosing state approaches
- Explanations of when to use URL vs. context state
- Examples with reasoning
AI Rule (in .cursor/rules/state-management.mdc
):
- Specific implementation patterns
- Code snippets showing correct approaches
- Technical specifications for each state type
- Integration details
Example 2: Testing
Human Documentation (in /docs/guides/testing-strategy.mdx
):
- Overall testing philosophy
- Coverage goals and metrics
- Visual representation of test pyramid
- Examples of good tests with explanations
AI Rule (in .cursor/rules/testing-guidelines.mdc
):
- Directory and file naming conventions
- Implementation patterns for test files
- Mock creation standards
- Technical specifications for assertions
Benefits of the Dual Approach
This approach offers several key benefits:
- Separation of Concerns: Each type of documentation focuses on what it does best
- Reduced Repetition: No need to make docs technical enough for implementation
- Better Adherence: Standards enforced by AI at the point of creation
- Improved Discoverability: Human docs can focus on learning and discovery
- Enhanced Consistency: Technical details don’t get lost in conceptual docs
- Complementary Coverage: Both systems cover what the other might miss
Maintenance Strategy
To keep both systems aligned:
- When making significant changes, update both human docs and AI rules
- Conduct quarterly audits to identify divergence
- Reference related documentation in rule files
- Mention rule existence in human documentation
- Use PR templates that prompt for documentation updates
Documentation Indexing
To ensure your documentation is discoverable in our documentation system:
- Add each new document to the
docs.json
file in the root of the/docs
directory - Specify the appropriate title, description, and category
- Add it to the correct section in the navigation structure
Example entry in docs.json
:
Without this entry, your documentation will not appear in the navigation menu or search results, making it effectively invisible to team members.
Conclusion
By separating human-focused documentation from AI-guided rules, we create a more effective knowledge management system. Humans get the context and reasoning they need, while AI gets the precise guidance required to generate code according to our standards.
This dual approach allows us to maintain consistent standards while preserving the knowledge that makes our codebase unique.