agentleFS
vfarcicvfarcic/dot-ai/CLAUDE.md

dot-ai

CLAUDE.md336 starsChanged 10 months agoMITView on GitHub

πŸ”΄ BEFORE MARKING ANY TASK/SUBTASK AS COMPLETE: β–‘ Integration Tests Written: Write integration tests for new functionality β–‘ All Tests Pass: Run npm run test:integration - ALL tests must pass β–‘ No Test Failures: Fix any failing tests before proceeding ❌ TASK IS NOT COMPLETE IF: - Any integration tests are failing - New code lacks integration test coverage - You haven't run npm run test:integration to verify

  • Reads credentials

The file

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

6 rules. About 0 are common, 2 are distinctive, and 4 are very specific to this project.

  • β‰ˆ0

    Common Β· estimate

    Many files like this have a rule of this kind.

  • β‰ˆ2

    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
  • could be automatic: a setting could enforce it
  1. Distinctive:

    Always Write Integration Tests: When making code changes, you MUST write or update integration tests

    line 20
  2. Very specific:

    Always Run All Tests: Before marking any task complete, run npm run test:integration

    line 21
  3. Distinctive:

    Always Check for Reusability: Search codebase for existing functions before implementing new ones

    line 23
  4. Very specific:

    Never Create Branches Directly β€” Always Use Worktrees: When starting feature work (including /prd-start), always use /worktree-prd to …

    line 25
  5. Very specific:

    Temporary Files: Always use ./tmp for any temporary files, never /tmp

    line 57
  6. Very specific:

    Running Integration Tests via CI: When the local cluster is unavailable (e.g., in use by parallel work), use workflow_dispatch in GitHub …

    line 63

β‰ˆ β€œ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

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

⚠️ MANDATORY TASK COMPLETION CHECKLIST ⚠️

πŸ”΄ BEFORE MARKING ANY TASK/SUBTASK AS COMPLETE:

β–‘ Integration Tests Written: Write integration tests for new functionality β–‘ All Tests Pass: Run npm run test:integration - ALL tests must pass β–‘ No Test Failures: Fix any failing tests before proceeding

❌ TASK IS NOT COMPLETE IF:

  • Any integration tests are failing
  • New code lacks integration test coverage
  • You haven't run npm run test:integration to verify

PERMANENT INSTRUCTIONS

  1. Always Write Integration Tests: When making code changes, you MUST write or update integration tests
  2. Always Run All Tests: Before marking any task complete, run npm run test:integration
  3. Never Claim Done with Failing Tests: A task is NOT complete if any tests are failing
  4. Always Check for Reusability: Search codebase for existing functions before implementing new ones
  5. Never Hardcode AI Prompts: All prompts go in prompts/ (internal) or shared-prompts/ (user-facing), loaded dynamically (see existing code for pattern). Both are shipped runtime directories listed in package.json files, so anything placed there is published in the npm package and copied into the Docker image. Dev-only evaluation prompts are an exception to the directory, never to the rule: they live beside the harness that reads them in src/evaluation/prompts/, are read from a repo checkout by npm run eval:*, and ship nowhere β€” leave them there rather than moving them into prompts/.
  6. Never Create Branches Directly β€” Always Use Worktrees: When starting feature work (including /prd-start), always use /worktree-prd to create an isolated worktree. Never run git checkout -b or git switch -c, even if a skill instructs you to.
  7. Always Configure New Params via Helm Chart Values: Every NEW configuration parameter must be a first-class value in charts/values.yaml, rendered into the container env by charts/templates/deployment.yaml β€” follow rbac.enforcement.enabled β†’ DOT_AI_RBAC_ENABLED, where the chart value is the user-facing contract and the env var is an internal detail. Never introduce a bare env var, and never document a new param under extraEnv (not even as an interim step). The many DOT_AI_* env vars in the codebase are legacy from when the project ran outside Kubernetes; it is Kubernetes-only now, so the chart is the single configuration interface. extraEnv remains valid only for pre-existing env vars (e.g. DOT_AI_GIT_TOKEN) and third-party config such as OTEL.
  8. Never Store Project Knowledge in Agent Memory: Anything learned about this project β€” conventions, decisions, gotchas, rationale β€” goes in the repo where the whole team and every agent can see it: this file for rules, docs/ for user-facing behavior, a PRD in prds/ for in-flight design. Never persist it to per-user agent memory outside the repo (e.g. ~/.claude/**/memory/), which teammates cannot see, code review cannot catch, and nothing keeps in sync with the code. The narrow exception is a fact true only of one machine or account (host tooling quirks, personal credentials paths) β€” that is not project knowledge and does not belong in the repo either.

Testing Workflow

npm run test:unit                    # Fast unit tests (no cluster)
npm run test:integration             # Full e2e tests (creates Kind cluster)
npm run test:integration version     # Run specific test by pattern
  • Long-running tests: Redirect to file, then check tail for pass/fail:
    npm run test:integration > ./tmp/test-output.log 2>&1
    tail -30 ./tmp/test-output.log  # Check result
    # Read full file only if failures detected
  • Cleanup after success: ./tests/integration/infrastructure/teardown-cluster.sh
  • Keep resources on failure for debugging

Directory-Specific Instructions

ALWAYS check for and follow CLAUDE.md files in subdirectories:

DirectoryKey Requirement
docs/Execute-then-document: Run commands, capture real output, then document
tests/integration/Use toMatchObject pattern, beforeAll cleanup, describe.concurrent

Project Conventions

Temporary Files: Always use ./tmp for any temporary files, never /tmp

Test Clusters: Integration tests create ./kubeconfig-test.yaml in project root

Git Commits: CI runs automatically on PRs targeting main. Use workflow_dispatch in GitHub Actions to manually trigger CI on any branch.

Running Integration Tests via CI: When the local cluster is unavailable (e.g., in use by parallel work), use workflow_dispatch in GitHub Actions to trigger the CI pipeline on your branch.

MCP vs Plugin Architecture

The codebase has two layers. Most features involve both working together.

MCP Server (src/) - Interface + Orchestration

  • Registers tools with clients (Claude Code, Cursor, etc.)
  • Interacts with AI models for reasoning
  • Orchestrates calls to plugin tools
  • Manages sessions and state

Plugins (packages/agentic-tools/) - Tool Implementations

  • Contains the actual tool logic (kubectl_, vector_, etc.)
  • Executes against external systems (Kubernetes, Qdrant)
  • Can run agentic loops for complex multi-step operations

Example flow for "what's the status of my cluster":

  1. MCP receives request β†’ calls AI for reasoning
  2. AI decides to invoke kubectl_get β†’ MCP routes to plugin
  3. Plugin executes kubectl, returns data
  4. MCP feeds result to AI for interpretation β†’ returns answer

When adding code, ask:

  • "Is this about registration, AI interaction, or routing?" β†’ MCP
  • "Is this tool implementation or external system execution?" β†’ Plugin

Note: MCP tool implementations are migrating to plugins over time. The direction is MCP as a thin orchestration layer with all tool logic in plugins.

Environment

# Required for AI features (only need one)
export ANTHROPIC_API_KEY=your_key
export OPENAI_API_KEY=your_key

# Optional
export AI_PROVIDER=anthropic          # anthropic, openai, google, xai, amazon_bedrock
export DEBUG_DOT_AI=true              # Debug logging to tmp/
export KUBECONFIG=/path/to/kubeconfig

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.