Documentation & AI Rules: A Dual Approach

CONA uses a dual approach to maintaining project knowledge and standards:

  1. Human-Focused Documentation - In the /docs directory
  2. 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:

AreaHuman DocumentationAI Rules
ArchitectureSystem diagrams, rationale, evolutionImplementation patterns, file organization
State ManagementDecision framework, conceptual modelCode patterns, specific approaches
TestingStrategy, coverage goals, philosophyImplementation standards, mock patterns
PerformanceCritical paths, benchmarks, goalsOptimization techniques, patterns to avoid

Implementation Guide

Creating Human Documentation

  1. Structure: Use MDX with clear headings and sections
  2. Content: Include context, reasoning, examples, and diagrams
  3. Location: Place in the appropriate /docs subdirectory
  4. Index Entry: Add the document to docs.json to make it discoverable
  5. Format: Follow our documentation style guide
  6. 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 to docs.json will make it invisible to users.

Creating AI Rules

  1. Structure: Use MDC with proper metadata headers
  2. Content: Focus on implementation patterns with code examples
  3. Location: Place in .cursor/rules directory
  4. Format: Follow concise, technically specific language
  5. 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:

  1. Separation of Concerns: Each type of documentation focuses on what it does best
  2. Reduced Repetition: No need to make docs technical enough for implementation
  3. Better Adherence: Standards enforced by AI at the point of creation
  4. Improved Discoverability: Human docs can focus on learning and discovery
  5. Enhanced Consistency: Technical details don’t get lost in conceptual docs
  6. Complementary Coverage: Both systems cover what the other might miss

Maintenance Strategy

To keep both systems aligned:

  1. When making significant changes, update both human docs and AI rules
  2. Conduct quarterly audits to identify divergence
  3. Reference related documentation in rule files
  4. Mention rule existence in human documentation
  5. Use PR templates that prompt for documentation updates

Documentation Indexing

To ensure your documentation is discoverable in our documentation system:

  1. Add each new document to the docs.json file in the root of the /docs directory
  2. Specify the appropriate title, description, and category
  3. Add it to the correct section in the navigation structure

Example entry in docs.json:

{
  "title": "Documentation & AI Rules",
  "description": "Understanding our dual approach to documentation",
  "path": "guides/documentation-and-rules",
  "category": "guides"
}

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.