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…
In this repository7 other files it gives its agents.
- claude-improve-configSkill
- docs-page-frontmatterSkill
- hypothesisSkill
- narwhalsSkill
- sybilSkill
- syrupySkill
- tachSkill
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
- Distinctive: line 5
Start each task with the planner agent.
- Distinctive: line 19
Use ASD-STE100 Simplified Technical English when you communicate with the user.
- Distinctive: line 36
Git commits: Do not create commits unless explicitly requested.
- Very specific: line 40
Always add or update tests when modifying features.
- Very specific: line 41
Never run the full test suite unless instructed.
- Very specific: line 42
Use uv run pytest --tach to automatically skip tests unaffected by your changes (uses tach's module dependency graph).
- Distinctive: line 43
Always use fixtures to setup data and common values.
- Very specific: line 47
Snapshot tests: If tests fail due to snapshot mismatches after intentional changes, update with uv run pytest --snapshot-update …
- Distinctive: line 51
Docstrings: Avoid documenting implementation details.
- Distinctive: line 53
Comments: Write comments that describe the current state of the code, not how it got there.
- Distinctive: line 55
Variable usage: Avoid introducing variables that are only used once.
- Distinctive: line 64
Write in complete English sentences.
≈ “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
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.pyto 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 testsuv run pytest tests/test_migrations.py::test_migration_generation - Use
uv run pytest --tachto 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 intests/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.
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.

