dot-ai
CLAUDE.md336 starsChanged 10 months agoMITView on GitHub
In this repository33 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- dot-ai-changelog-fragmentSkill
- dot-ai-generate-cicdSkill
- dot-ai-generate-dockerfileSkill
- dot-ai-impact_analysisSkill
- dot-ai-manageKnowledgeSkill
- dot-ai-manageOrgDataSkill
- dot-ai-operateSkill
- dot-ai-prd-closeSkill
- dot-ai-prd-createSkill
- dot-ai-prd-doneSkill
- dot-ai-prd-fullSkill
- dot-ai-prd-nextSkill
- dot-ai-prds-getSkill
- dot-ai-prd-startSkill
- dot-ai-prd-update-decisionsSkill
- dot-ai-prd-update-progressSkill
- dot-ai-process-feature-requestSkill
- dot-ai-projectSetupSkill
- dot-ai-query-dot-aiSkill
- dot-ai-querySkill
- dot-ai-recommendSkill
- dot-ai-remediateSkill
- dot-ai-request-dot-ai-featureSkill
- dot-aiSkill
- dot-ai-tag-releaseSkill
- dot-ai-usersSkill
- dot-ai-versionSkill
- dot-ai-worktree-prdSkill
- dot-ai-write-docsSkill
- infographic-generatorSkill
- publish-mock-serverSkill
- write-docsSkill
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
- Very specific: line 6
Filename format: Use kebab-case with descriptive names (overview.md, deployment.md, knowledge-base.md)
- Very specific: line 8
Consistent naming: Use short, descriptive names within their directory context (e.g., ai-engine/tools/query.md, …
- Distinctive: line 12
Overview section: Always include "What it does", "Use when", and "📖 Full Guide" links where applicable
- Very specific: line 13
Table format: Use comparison tables for method/option comparisons with Pros/Cons/Best For columns
- Distinctive: line 14
Status indicators: Use emoji indicators (✅ ❌ 🎯 🚀 🔧) for recommendations and status
- Very specific: line 15
Code blocks: Always use syntax highlighting (`
bash,yaml, ``json) - Distinctive: line 17
Decision trees: Use clear "🎯 Recommended" and alternative flow patterns
- Distinctive: line 34
Check current tool capabilities: - never assume features exist without testing
- Distinctive: line 39
Test with different environments: if the command is environment-dependent
- Distinctive: line 45
Test with realistic values: not just placeholder examples
- Distinctive: line 48
Accuracy first: Never guess command syntax or outputs - always verify
- Distinctive: line 49
Real examples: Use actual working examples from testing, not theoretical ones
- Distinctive: line 50
Current information: Verify feature availability and syntax before documenting
- Distinctive: line 51
User perspective: Write from the user's workflow perspective, not implementation details
- Distinctive: line 54
Keep README.md current: When adding new major features or setup methods to docs, update the root README.md
- Distinctive: line 55
Maintain consistency: Ensure terminology and descriptions match between README.md and detailed docs
- Distinctive: line 56
Update cross-references: When restructuring docs, update README.md links
- Distinctive: line 65
Document that item with real output
- Distinctive: line 80
Start MCP client (Claude Code, Cursor, etc.)
- Distinctive: line 81
Use features through MCP client interaction
- Distinctive: line 109
VALIDATION CHECK: If documentation includes commands users type in terminal (other than MCP client setup), it's probably wrong.
≈ “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.
Files
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) ormcp/(MCP-specific). Withinai-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:::infotext 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:
- Execute the command or call the MCP tool to verify it works
- Capture actual output and use real output in examples (not placeholder text)
- Test error scenarios to ensure error examples are accurate
- 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:
- Execute it and capture actual output
- Document that item with real output
- 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.jsonconfiguration - 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 logsfor MCP server (users won't typically run this)curlto 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.
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
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.

