agentleFS
anam-organam-org/metaxy/CLAUDE.md

metaxy

CLAUDE.md126 starsChanged 9 months agoApache-2.0View on GitHub

Start each task with the planner agent. Use python-dev to write code, python-test-engineer to write tests. Iterate until qa is satisfied. Always invoke the /dignified-python skill before writing or reviewing Python code. This skill enforces LBYL exception handling, modern type syntax, pathlib usage, and other project standards. Active Development - Stable Public API The project has users. APIs marked with @public cannot have breaking changes between minor releases. Non-public internals can be refactored freely. Deprecated APIs must be preserved until…

The file

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

12 rules. About 0 are common, 8 are distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈8

    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:

    Start each task with the planner agent.

    line 5
  2. Distinctive:

    Use ASD-STE100 Simplified Technical English when you communicate with the user.

    line 19
  3. Distinctive:

    Git commits: Do not create commits unless explicitly requested.

    line 36
  4. Very specific:

    Always add or update tests when modifying features.

    line 40
  5. Very specific:

    Never run the full test suite unless instructed.

    line 41
  6. Very specific:

    Use uv run pytest --tach to automatically skip tests unaffected by your changes (uses tach's module dependency graph).

    line 42
  7. Distinctive:

    Always use fixtures to setup data and common values.

    line 43
  8. Very specific:

    Snapshot tests: If tests fail due to snapshot mismatches after intentional changes, update with uv run pytest --snapshot-update …

    line 47
  9. Distinctive:

    Docstrings: Avoid documenting implementation details.

    line 51
  10. Distinctive:

    Comments: Write comments that describe the current state of the code, not how it got there.

    line 53
  11. Distinctive:

    Variable usage: Avoid introducing variables that are only used once.

    line 55
  12. Distinctive:

    Write in complete English sentences.

    line 64

≈ “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

Agent Workflow

Start each task with the planner agent. Use python-dev to write code, python-test-engineer to write tests. Iterate until qa is satisfied.

Python Code Standards

Always invoke the /dignified-python skill before writing or reviewing Python code. This skill enforces LBYL exception handling, modern type syntax, pathlib usage, and other project standards.

Project Status

Active Development - Stable Public API

The project has users. APIs marked with @public cannot have breaking changes between minor releases. Non-public internals can be refactored freely. Deprecated APIs must be preserved until a minor release.

Communication

Use ASD-STE100 Simplified Technical English when you communicate with the user. Use short sentences, active voice, and consistent terms. Keep code identifiers, API names, and quoted source text exact. State the result and any limits clearly.

Project Overview

Metaxy is a feature metadata management system for multimodal ML pipelines. It tracks feature versions, dependencies, and data lineage with declarative definitions, automatic change detection, and smart migrations.

Commands

just sync        # Install all dependencies
just ruff        # Lint and format
just typecheck   # Type check with ty
uv run pytest    # Run tests (add -k "pattern" to filter)

Guardrails

Git commits: Do not create commits unless explicitly requested. When asked to commit, follow standard git workflow.

Tests:

  • Always add or update tests when modifying features. Run uv run pytest tests/path/to/test.py to verify changes before considering work complete.
  • Never run the full test suite unless instructed. Only run relevant tests by filtering with -k "pattern", specific files or specific tests uv run pytest tests/test_migrations.py::test_migration_generation
  • Use uv run pytest --tach to automatically skip tests unaffected by your changes (uses tach's module dependency graph). Prefer this over running the full suite.
  • Always use fixtures to setup data and common values. Always request fixtures with appropriate type annotations.

Type safety: Code must pass just typecheck. Fix type errors before submitting.

Snapshot tests: If tests fail due to snapshot mismatches after intentional changes, update with uv run pytest --snapshot-update path/to/test.py.

Error handling: Fail fast with clean errors. Do not catch exceptions to handle them gracefully. Let errors propagate with clear messages. Avoid try/except blocks unless re-raising with additional context.

Docstrings: Avoid documenting implementation details. Focus on high-level concepts, properties and invariants. Avoid documenting default values as they are already documented in the code.

Comments: Write comments that describe the current state of the code, not how it got there. Do not reference refactoring history, deleted code, or previous implementations (e.g., avoid "using X because Y was removed" or "previously this used Z").

Variable usage: Avoid introducing variables that are only used once. Prefer method chaining and inline expressions. Exception: use a named variable when it clarifies non-obvious meaning or intent.

When to Consult Docs

  • Architecture decisions or unfamiliar patterns: See docs/guide/ for concepts like feature graphs, migrations, and metadata stores
  • Backend-specific issues (DuckDB, ClickHouse, BigQuery): Check docs/integrations/metadata-stores/ and corresponding test files in tests/metadata_stores/

Writing Docs

Write in complete English sentences. Do not use (braces) excessively. Explain concepts clearly and concisely. First provide a generic explanation, then give a concrete example if necessary. Use Material for Mkdocs features: tooltips and admonitions to keep examples aside from the main flow.

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.