​

Documentation vs Rules Strategy

​

Overview

CONA maintains two parallel information systems:

1. Human Documentation (/docs directory) - Designed for human consumption
2. AI Rules (.cursor/rules directory) - Designed to guide AI behavior

This guide provides guidance on when to create documentation, when to create rules, and how to ensure they remain aligned.

​

When to Create Human Documentation

Create documentation in the /docs directory when:

• Explaining complex business concepts
• Providing step-by-step guides for workflows
• Illustrating architecture with diagrams
• Explaining the “why” behind decisions
• Teaching new developers about the system
• Providing context for non-technical stakeholders

Human documentation should be comprehensive, visual, and instructional.

​

When to Create AI Rules

Create rules in the .cursor/rules directory when:

• Defining coding standards that should be consistently applied
• Specifying project-specific patterns for code generation
• Providing technical implementation details
• Defining naming conventions and file structures
• Specifying integration details with third-party services
• Guiding AI on framework-specific best practices

AI rules should be concise, specific, and actionable.

​

Bidirectional Documentation Approach

For critical areas, maintain both:

1. Human Documentation - Explaining concepts with examples and visuals
2. AI Rules - Providing implementation guidelines and patterns

These areas include:

• Core architecture patterns
• State management approaches
• Testing methodologies
• Performance optimization strategies
• Error handling patterns

​

Rule Creation Guidelines

When creating a new rule:

1. Check if human documentation exists first
2. Ensure rule aligns with existing documentation
3. Add appropriate metadata headers
4. Use concise, technical language
5. Include code examples wherever possible
6. Reference relevant files using @filename notation

​

Documentation Creation Guidelines

When creating new documentation:

1. Check if AI rules exist for the topic
2. Ensure documentation aligns with rules
3. Focus on conceptual understanding and context
4. Include diagrams where appropriate
5. Use examples that match the examples in rules

​

Maintaining Alignment

To ensure alignment between documentation and rules:

1. Update both when making significant changes
2. Periodically audit for inconsistencies
3. Link to related documentation in rule files using comments
4. Reference rule existence in documentation

Remember: Documentation explains the “why” and “what”; rules guide the “how”.