agentleFS
vfarcicvfarcic/dot-ai/docs/CLAUDE.md

dot-ai

CLAUDE.md336 starsChanged 10 months agoMITView on GitHub

The file

Show its rules and text

We split this CLAUDE.md into the rules it gives an agent

21 rules. About 0 are common, 17 are distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈17

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Filename format: Use kebab-case with descriptive names (overview.md, deployment.md, knowledge-base.md)

    line 6
  2. Very specific:

    Consistent naming: Use short, descriptive names within their directory context (e.g., ai-engine/tools/query.md, …

    line 8
  3. Distinctive:

    Overview section: Always include "What it does", "Use when", and "📖 Full Guide" links where applicable

    line 12
  4. Very specific:

    Table format: Use comparison tables for method/option comparisons with Pros/Cons/Best For columns

    line 13
  5. Distinctive:

    Status indicators: Use emoji indicators (✅ ❌ 🎯 🚀 🔧) for recommendations and status

    line 14
  6. Very specific:

    Code blocks: Always use syntax highlighting (`bash, yaml, ``json)

    line 15
  7. Distinctive:

    Decision trees: Use clear "🎯 Recommended" and alternative flow patterns

    line 17
  8. Distinctive:

    Check current tool capabilities: - never assume features exist without testing

    line 34
  9. Distinctive:

    Test with different environments: if the command is environment-dependent

    line 39
  10. Distinctive:

    Test with realistic values: not just placeholder examples

    line 45
  11. Distinctive:

    Accuracy first: Never guess command syntax or outputs - always verify

    line 48
  12. Distinctive:

    Real examples: Use actual working examples from testing, not theoretical ones

    line 49
  13. Distinctive:

    Current information: Verify feature availability and syntax before documenting

    line 50
  14. Distinctive:

    User perspective: Write from the user's workflow perspective, not implementation details

    line 51
  15. Distinctive:

    Keep README.md current: When adding new major features or setup methods to docs, update the root README.md

    line 54
  16. Distinctive:

    Maintain consistency: Ensure terminology and descriptions match between README.md and detailed docs

    line 55
  17. Distinctive:

    Update cross-references: When restructuring docs, update README.md links

    line 56
  18. Distinctive:

    Document that item with real output

    line 65
  19. Distinctive:

    Start MCP client (Claude Code, Cursor, etc.)

    line 80
  20. Distinctive:

    Use features through MCP client interaction

    line 81
  21. Distinctive:

    VALIDATION CHECK: If documentation includes commands users type in terminal (other than MCP client setup), it's probably wrong.

    line 109

≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

Documentation Directory - Claude Code Instructions

Documentation Standards & Format

File Structure Requirements

  • Filename format: Use kebab-case with descriptive names (overview.md, deployment.md, knowledge-base.md)
  • Directory organization: Docs live under ai-engine/ (the product) or mcp/ (MCP-specific). Within ai-engine/, group by concern: tools/, setup/, organizational-data/, operations/, api/
  • Consistent naming: Use short, descriptive names within their directory context (e.g., ai-engine/tools/query.md, ai-engine/setup/deployment.md) — no prefixes needed since the directory provides context

Documentation Format Standards

  • H1 Title: One H1 per file with descriptive title and bold summary line
  • Overview section: Always include "What it does", "Use when", and "📖 Full Guide" links where applicable
  • Table format: Use comparison tables for method/option comparisons with Pros/Cons/Best For columns
  • Status indicators: Use emoji indicators (✅ ❌ 🎯 🚀 🔧) for recommendations and status
  • Code blocks: Always use syntax highlighting (bash, yaml, ```json)
  • Cross-references: Link related documentation with relative paths
  • Decision trees: Use clear "🎯 Recommended" and alternative flow patterns
  • Portable Markdown only: Docs are read both as raw Markdown on GitHub and through Docusaurus, so use syntax both engines understand. For callouts use plain > blockquotes — never :::info / :::note / :::tip (Docusaurus-only; renders as literal :::info text on GitHub) and never > [!NOTE] / > [!WARNING] GitHub alerts (GitHub-only; renders as a blockquote with literal [!NOTE] text in Docusaurus)

Command and Example Validation Rules

🚨 CRITICAL REQUIREMENT: All commands and examples MUST be validated before inclusion

Before Adding Any Command or MCP Tool Example:

  1. Execute the command or call the MCP tool to verify it works
  2. Capture actual output and use real output in examples (not placeholder text)
  3. Test error scenarios to ensure error examples are accurate
  4. Verify syntax - especially for complex commands with multiple parameters

For MCP Tool Documentation:

  • Test each tool call with realistic parameters before documenting
  • Use actual responses in examples instead of "..." or placeholder content
  • Validate parameter requirements by testing with missing/invalid parameters
  • Check current tool capabilities - never assume features exist without testing

For Shell Commands:

  • Run every command in a test environment before documenting
  • Include actual output where relevant (truncated if very long)
  • Test with different environments if the command is environment-dependent
  • Verify prerequisites by testing without required dependencies

For Configuration Examples:

  • Test configuration files to ensure they work as documented
  • Validate YAML/JSON syntax using parsers
  • Test with realistic values not just placeholder examples

Content Quality Standards

  • Accuracy first: Never guess command syntax or outputs - always verify
  • Real examples: Use actual working examples from testing, not theoretical ones
  • Current information: Verify feature availability and syntax before documenting
  • User perspective: Write from the user's workflow perspective, not implementation details

README.md Coordination

  • Keep README.md current: When adding new major features or setup methods to docs, update the root README.md
  • Maintain consistency: Ensure terminology and descriptions match between README.md and detailed docs
  • Update cross-references: When restructuring docs, update README.md links
  • Sync feature lists: Major feature additions should be reflected in both README.md overview and detailed guides

Validation Workflow

🚨 MANDATORY: Execute-then-document, one item at a time.

For each command/example in documentation:

  1. Execute it and capture actual output
  2. Document that item with real output
  3. Move to next item and repeat

NEVER batch-write multiple examples then test afterward. Validate each step before proceeding to the next.

⚠️ MCP DOCUMENTATION ANTI-PATTERNS (NEVER DO THIS)

CRITICAL: MCP Client Workflow Alignment

❌ Manual Server Commands: Never document commands users run directly:

  • node dist/mcp/server.js (users never run this)
  • Direct HTTP calls to the MCP server (users interact through MCP clients)

✅ MCP Client Workflow: Document only what users actually do:

  • Create .mcp.json configuration
  • Start MCP client (Claude Code, Cursor, etc.)
  • Use features through MCP client interaction

❌ Server Lifecycle Management: Never document manual server operations:

  • Starting/stopping servers manually
  • Restarting services for troubleshooting
  • Manual container/process management

✅ Client-Managed Lifecycle: Document that MCP client handles everything:

  • Client starts servers automatically
  • Client manages server lifecycle
  • Client handles cleanup when needed

❌ Manual Debugging Commands: Never document CLI debugging:

  • kubectl logs for MCP server (users won't typically run this)
  • curl to MCP endpoints (users won't run this)
  • Manual health checks or status commands

✅ MCP-Based Diagnostics: Use client-integrated diagnostics:

  • "Show dot-ai status" command (primary diagnostic)
  • Client-visible error messages
  • MCP tool-based troubleshooting

WHY THIS MATTERS:

  • Users interact with MCP servers through clients, not directly
  • Manual commands create documentation that doesn't match actual user workflow
  • Creates confusion between "how it works" vs "how users use it"
  • Violates the fundamental MCP interaction pattern

VALIDATION CHECK: If documentation includes commands users type in terminal (other than MCP client setup), it's probably wrong.

Common Mistakes to Avoid

  • ❌ Adding command examples without testing them first
  • ❌ Using outdated or deprecated syntax
  • ❌ Copying examples from other projects without validation
  • ❌ Assuming MCP tool parameters or outputs without testing
  • ❌ Forgetting to update README.md when adding major new documentation
  • ❌ Using placeholder text instead of real examples
  • ❌ Documenting manual server commands instead of MCP client workflow
  • ❌ Including debugging commands users won't actually run

Remember: Documentation credibility depends on accuracy. One broken example undermines trust in the entire guide.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.