agentleFS
anam-organam-org/metaxy/.claude/skills/tach/SKILL.md

tach

Skill126 starsChanged 9 months agoApache-2.0View on GitHub

This skill should be used when the user asks to "add a tach module", "configure tach layers", "define module boundaries", "set up interfaces", "run tach check", "check module boundaries", "tach sync", "tach show", "deprecate a dependency", "tach-ignore", "unchecked modules", "tach test", "skip tests with tach", "configure tach.toml", "source roots", "forbid circular dependencies", "enforce module boundaries", "set up architectural layers", or "tach init".

The file

We split this skill into the rules it gives an agent

9 rules. About 0 are common, 0 are distinctive, and 9 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 9

    Very specific

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

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

    Run uv run tach check to verify boundaries.

    line 16
  2. Very specific:

    Run uv run pytest --tach to skip tests unaffected by changes (uses tach's module dependency graph for impact analysis).

    line 18
  3. Very specific:

    Add the module definition to tach.toml with path, layer, and depends_on

    line 107
  4. Very specific:

    Run tach sync --add to discover any additional dependencies

    line 108
  5. Very specific:

    Run tach check to verify

    line 109
  6. Very specific:

    Update the layer field in tach.toml

    line 113
  7. Very specific:

    Run tach check to verify no violations

    line 115
  8. Very specific:

    Add the dependency to depends_on in tach.toml

    line 122
  9. Very specific:

    Use # tach-ignore for exceptions

    line 124

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill 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
SKILL.md

Tach

Tach enforces module boundaries in Python codebases. It verifies that imports between modules respect declared dependencies and public interfaces, with no runtime impact.

For full documentation: https://docs.gauge.sh/

How This Project Uses Tach

The project defines three architectural layers in tach.toml: cli > ext > core. Higher layers may import from lower layers without declaring dependencies. Same-layer imports require explicit depends_on declarations. Unlayered facade and primitive modules (e.g., metaxy, metaxy._decorators) sit outside the layer hierarchy.

Run uv run tach check to verify boundaries. The pre-commit hook runs this automatically on src/ changes.

Run uv run pytest --tach to skip tests unaffected by changes (uses tach's module dependency graph for impact analysis).

Core Commands

CommandPurpose
tach initGuided setup: walks through tach mod, tach sync, tach show
tach modInteractive terminal UI to mark module boundaries
tach syncSync tach.toml with actual imports (--add to only add)
tach checkReport boundary/interface violations (--exact for unused deps)
tach check-externalValidate 3rd-party imports match pyproject.toml
tach showVisualize dependency graph (--web, --mermaid, -o)
tach mapJSON dependency map between files (--closure for transitives)
tach reportDependencies/usages of a module (--dependencies, --usages)
tach testRun only tests impacted by changes
tach installInstall as pre-commit hook

Full command reference: https://docs.gauge.sh/usage/commands/

Key Concepts

Modules

A module is a Python package or file with dependencies configured in tach.toml. Identified by import path from the nearest source root (e.g., metaxy.config for src/metaxy/config/).

[[modules]]
path = "metaxy.config"
layer = "core"
depends_on = ["metaxy._decorators", "metaxy.models"]

Special attributes:

  • utility: true — accessible to all modules without declaring dependency
  • unchecked: true — no dependency restrictions (for incremental adoption)
  • visibility: [] — isolate module from external imports
  • cannot_depend_on — forbidden dependencies (takes precedence over depends_on)

Layers

Ordered architectural tiers. Higher layers may freely import from lower layers; lower layers may never import from higher layers. Same-layer imports require explicit depends_on.

layers = ["cli", "ext", "core"]

Set layers_explicit_depends_on = true to require all cross-layer dependencies be declared explicitly. Mark a layer as closed with { name = "commands", closed = true } to force higher layers through the intermediary.

Full layers documentation: https://docs.gauge.sh/usage/layers/

Interfaces

Define public APIs to prevent deep coupling. Only imports matching expose patterns are allowed.

[[interfaces]]
expose = ["get_data"]
from = ["core"]

Interfaces support visibility to restrict consumers and exclusive: true to override other interfaces.

Full interfaces documentation: https://docs.gauge.sh/usage/interfaces/

Deprecation

Mark dependencies as deprecated to surface usage without failing checks:

depends_on = [{ path = "core", deprecated = true }]

tach-ignore

Suppress specific violations with inline comments:

# tach-ignore
from core.main import private_function

from core.api import priv, pub  # tach-ignore priv

Add reasons: # tach-ignore(reason here) member_name

Common Tasks

Add a New Module

  1. Add the module definition to tach.toml with path, layer, and depends_on
  2. Run tach sync --add to discover any additional dependencies
  3. Run tach check to verify

Move a Module Between Layers

  1. Update the layer field in tach.toml
  2. Adjust depends_on based on new layer relationships
  3. Run tach check to verify no violations

Debug Boundary Violations

Error format: file.py[L8]: Cannot import 'foo.bar'. Module 'baz' cannot depend on 'foo'.

Options:

  1. Add the dependency to depends_on in tach.toml
  2. Mark dependency as deprecated to track without blocking
  3. Use # tach-ignore for exceptions
  4. Restructure imports to go through public interfaces

Configuration Reference

Full configuration documentation: https://docs.gauge.sh/usage/configuration/

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.