architecture-as-code-python
Skill88 starsChanged 3 days agoMITView on GitHub
Python implementation of the `architecture-as-code` pattern. Per-package `architecture.toml` files merged into a single `import-linter` config and enforced via `lint-imports` (over a Grimp-built import graph). TRIGGER when: implementing or extending architecture-as-code in a Python repo, debugging an `import-linter` contract, or adapting the assembler. SKIP for routine edits inside a governed package. Reads in conjunction with `architecture-as-code` (the pattern, source of truth for schema, rule placement, anti-patterns, and audit checklist) — this skill defines only the Python-specific encoding, assembler code, and gotchas.
- Installs packages
In this repository52 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- alchemy-orchestrateSkill
- alchemySkill
- architecture-as-code-javascriptSkill
- architecture-as-code-pythonSkill
- architecture-as-codeSkill
- architecture-guidelinesSkill
- bring-downSkill
- ci-cd-reliability-architectureSkill
- continuous-improvementSkill
- defect-shift-leftSkill
- dependency-lifecycleSkill
- evolutionary-database-designSkill
- functionality-complexity-tradeoffSkill
- gate-lifecycleSkill
- implementation-readinessSkill
- infrastructure-fitSkill
- morphogenetic-architectureSkill
- observability-designSkill
- push-outSkill
- requirements-groundingSkill
- requirements-topologySkill
- requirements-traceabilitySkill
- structural-simplificationSkill
- system-optimizationSkill
- test-strategySkill
- zero-copy-requirementsSkill
- alchemy-orchestrateSkill
- alchemySkill
- architecture-as-code-javascriptSkill
- architecture-as-codeSkill
- architecture-guidelinesSkill
- bring-downSkill
- ci-cd-reliability-architectureSkill
- continuous-improvementSkill
- defect-shift-leftSkill
- dependency-lifecycleSkill
- evolutionary-database-designSkill
- functionality-complexity-tradeoffSkill
- gate-lifecycleSkill
- implementation-readinessSkill
- infrastructure-fitSkill
- morphogenetic-architectureSkill
- observability-designSkill
- push-outSkill
- requirements-groundingSkill
- requirements-topologySkill
- requirements-traceabilitySkill
- structural-simplificationSkill
- system-optimizationSkill
- test-strategySkill
- zero-copy-requirementsSkill
The file
We split this skill into the rules it gives an agent
1 rule. About 0 are common, 1 is distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 233
When applying this implementation, emit:
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 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.
Files
Architecture-as-Code — Python Implementation
Prerequisite. Read
architecture-as-codefirst. The schema (§1), subsystems (§2), forbidden edges (§3), rule placement (§4), assembler concept (§5), and anti-patterns / audit (§6) are defined there and apply identically here. This file documents only what is Python-specific.
1. File format
- Filename:
architecture.toml. Plain TOML — no Python code, no imports. - TOML arrays-of-tables:
[[subsystems]],[[forbidden]].[[components]]is read as a deprecated alias for[[subsystems]](§3). - Pattern syntax: dotted module paths (
mypkg.core.tier1). The package and all submodules match by default; setsingle = trueto match only the exact module. - Subsystem patterns may overlap (e.g.
mypkg.coreandmypkg.core.tier1both match files undermypkg/core/tier1/). That's fine — import-linter checks each contract independently; there's no first-match-wins.
# architecture.toml — example for a package with internal layering
[[subsystems]]
name = "core-facade"
pattern = "mypkg.core.api" # public sub-package = the facade
[[subsystems]]
name = "core-tier1"
pattern = "mypkg.core.tier1"
[[subsystems]]
name = "core-tier3"
pattern = "mypkg.core.tier3"
[[subsystems]]
name = "core-other"
pattern = "mypkg.core" # whole-package catch-all, last
[[forbidden]]
# Efferent — self-knowledge, lives in own file.
from = "core-*"
to = "*"
except_to = ["core-*"]
why = "Core purity: no imports outside the core package."
[[forbidden]]
# Internal layering.
from = "core-tier3"
to = "core-tier1"
why = "Tier 3 must go through tier 2."Parametric "not equal" syntax for cross-domain isolation:
!{from.captured.domain} (single braces).
[!NOTE] Facade pattern in Python. Python's idiomatic facade is a sub-package (e.g.
mypkg.core.api) exposing public API via__init__.pyand__all__. The "single file as facade" pattern from the JS skill maps awkwardly here; prefer a public sub-package plus forbidden edges that ban imports to the internal sub-packages.
2. Specialized contract types
The assembler emits forbidden contracts by default. For two common shapes
import-linter offers more specific contract types that produce cleaner
violations:
- Sibling-isolation across N subsystems → one
independencecontract listing the N module patterns. - Strict tier ordering (e.g.
tier1 < tier2 < tier3, where higher tiers may import lower) → alayerscontract. Optional — explicit[[forbidden]]edges between specific tiers also work.
3. Assembler
A small Python script invoked by pre-commit and CI. Discovers all
architecture.toml files, merges them, generates a .importlinter config in
INI form, and invokes lint-imports.
Why generate .importlinter rather than mutate pyproject.toml?
The generated file is a build artifact (gitignored alongside
.import_linter_cache/); the source of truth is the per-package
architecture.tomls. import-linter natively reads .importlinter ahead of
pyproject.toml.
# tools/arch_lint.py
import subprocess
import sys
import tomllib
from pathlib import Path
# Coverage gate (pattern Directive 7): the graph roots must cover every source
# package. Derive them; one hardcoded root silently excludes whatever top-level
# directory lands next.
SOURCE_PACKAGES = sorted(
p.name
for p in Path(".").iterdir()
if p.is_dir() and (p / "__init__.py").exists() and not p.name.startswith(".")
)
GENERATED_CONFIG = Path(".importlinter")
# 1. Discover — recursive walk, skipping the configured ignore-list
# (.venv, dist, build, .tox, __pycache__, .import_linter_cache).
arch_files = sorted(
Path(".").rglob("architecture.toml"),
key=lambda p: -len(p.parts), # deeper-first
)
# 2. Concat. [[components]] is the deprecated alias for [[subsystems]]
# (pattern Directive 1): warn on it, reject a file that carries both.
subsystems, forbidden = [], []
for f in arch_files:
data = tomllib.loads(f.read_text(encoding="utf-8"))
if "subsystems" in data and "components" in data:
sys.exit(f"{f}: declare [[subsystems]] or [[components]], not both")
if "components" in data:
print(f"{f}: [[components]] is a deprecated alias for [[subsystems]]", file=sys.stderr)
subsystems.extend(data.get("subsystems", data.get("components", [])))
forbidden.extend(data.get("forbidden", []))
# 3. Expand wildcards against the live registry.
names = [c["name"] for c in subsystems]
def expand(spec, except_=None):
if isinstance(spec, dict):
return spec # parametric — handled separately
items = spec if isinstance(spec, list) else [spec]
def resolve(lst):
out = []
for t in lst:
if t == "*":
out.extend(names)
elif t.endswith("*"):
p = t[:-1]
out.extend(n for n in names if n.startswith(p))
else:
out.append(t)
return out
types = resolve(items)
if except_:
sub = set(resolve(except_))
types = [t for t in types if t not in sub]
return types
# 4. Emit import-linter contracts (INI format).
subsystem_pattern = {c["name"]: c["pattern"] for c in subsystems}
subsystem_single = {c["name"]: c.get("single", False) for c in subsystems}
if not SOURCE_PACKAGES:
sys.exit("No source packages discovered — the import graph would be empty.")
ini = ["[importlinter]", "root_packages ="]
ini.extend(f" {p}" for p in SOURCE_PACKAGES)
ini.append("")
for i, edge in enumerate(forbidden):
src = expand(edge["from"], edge.get("except"))
dst = expand(edge["to"], edge.get("except_to"))
if not src or not dst:
continue # nothing to forbid after exceptions
src_modules = [subsystem_pattern[n] for n in src]
dst_modules = [subsystem_pattern[n] for n in dst]
as_packages = not any(subsystem_single[n] for n in src + dst)
ini.append(f"[importlinter:contract:{i}]")
ini.append(f"name = {edge['why'][:80]}")
ini.append("type = forbidden")
ini.append("source_modules =")
ini.extend(f" {m}" for m in src_modules)
ini.append("forbidden_modules =")
ini.extend(f" {m}" for m in dst_modules)
if not as_packages:
ini.append("as_packages = False")
ini.append("")
GENERATED_CONFIG.write_text("\n".join(ini), encoding="utf-8")
# 5. Invoke lint-imports
result = subprocess.run(
["lint-imports", "--config", str(GENERATED_CONFIG)],
check=False,
)
sys.exit(result.returncode)Install & run:
pip install import-linter # pulls in grimp; tomli on Python <3.11
python tools/arch_lint.py # discover + assemble + lintPre-commit hook:
# .pre-commit-config.yaml
repos:
- repo: local
hooks:
- id: arch-lint
name: "Architecture lint"
entry: "python tools/arch_lint.py"
language: system
pass_filenames: falselanguage: system is required — lint-imports must run inside the
project's virtualenv to import the analyzed packages.
Gitignore:
.importlinter # generated by tools/arch_lint.py
.import_linter_cache/ # import-linter's own cache4. Output Contract
When applying this implementation, emit:
Scope: <repo / package / subsystem path>
Decision: Add architecture.toml | Update assembler | Update import-linter config | Blocked
Generated config:<path, if any>
Contracts changed:<forbidden / layers / independence contracts>
Verification: <lint-imports command / assembler command / Not run + reason>
Next action: <specific file edit, package install, cache clear, or unresolved question>5. Python-specific gotchas
[!NOTE] Dynamic imports bypass enforcement. import-linter reads static
importandfrom ... importstatements via Grimp. Imports throughimportlib.import_module(...),__import__, or string-based dispatch don't appear in the graph. If a package uses dynamic imports for plugin loading, mark the entry-point as a single-module declared subsystem (single = true) so its rules are explicit, and consider banning the dynamic style elsewhere.
[!IMPORTANT] The graph root is the coverage gate. import-linter builds its graph from
root_package/root_packages. A new top-level package or directory outside that list is not in the graph, so no contract can fail on it and the run still reports success — the Python form of pattern Directive 7 ("the emitted rule's scope must equal the linted source set"). Deriveroot_packagesfrom the tree at assembly time rather than hardcoding one root, and fail the assembler when the derived list is empty or a top-level source package is missing. import-linter has no native file-existence rule (Directive 8), so that comparison — packages on disk vs. packages in the generated config — is the check that catches an undeclared directory.
[!NOTE] import-linter
*is single-segment. Inforbidden_modulesand similar fields,mypkg.*matchesmypkg.foobut notmypkg.foo.bar. The pattern's prefix wildcards (core-*) operate on subsystem names and are expanded by the assembler before contracts are emitted, so they don't hit this limit. But if you write raw module patterns yourself, mind the difference.
[!NOTE] import-linter forbids; it never requires. An aspect coverage check — every subsystem in the governed set uses the mechanism — has no contract type. Express it as a grimp-based test over the same registry;
defect-shift-leftplaces that check.
[!NOTE] Cache staleness during refactors.
.import_linter_cache/speeds up subsequent runs but can mislead during heavy refactors. Delete it if results don't match what your import statements actually say.
[!NOTE] Root package must be importable. import-linter imports the root package to walk it. Make sure
pip install -e .(or equivalent) has been run in the active venv before invoking the assembler.
[!NOTE] Mixing pattern-level and subsystem-level wildcards. A single rule that uses both
mypkg.*(single-segment, import-linter native) andcore-*(multi-match, assembler-expanded) will surprise you. Subsystem- name wildcards are the assembler's domain; raw*in import-linter patterns is single-segment only. Don't mix in one rule.
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.

