Fensu (フェンス) - Fensu<br>Documentation Index<br>Fetch the complete documentation index at: /llms.txt<br>Use this file to discover all available pages before exploring further.

Skip to main content

Search...

Navigation<br>Getting Started<br>Fensu (フェンス)

:first-child]:hidden! peer-[.is-custom]:[&>:first-child]:sm:hidden! peer-[.is-custom]:[&>:first-child]:md:hidden! peer-[.is-custom]:[&>:first-child]:lg:hidden! peer-[.is-custom]:[&>:first-child]:xl:hidden! peer-[.is-center]:[&>:first-child]:hidden! peer-[.is-center]:[&>:first-child]:sm:hidden! peer-[.is-center]:[&>:first-child]:md:hidden! peer-[.is-center]:[&>:first-child]:lg:hidden! peer-[.is-center]:[&>:first-child]:xl:hidden!">

Fensu means “fence” in Japanese.

Most linters catch bad code inside files. Fensu catches architectural drift:<br>code crossing the wrong boundary, living in the wrong module, or growing into the<br>wrong shape.<br>A repo small enough to fit in one file does not need Fensu. The trouble starts as<br>it grows: code moves, teams change, lessons get forgotten, and the mental map<br>decays.<br>Tests help preserve behavior, but nothing preserves the shape of the repo: what<br>belongs where, which layer owns what, which modules are public surfaces. That<br>consistency usually lives in code review and in people’s heads.<br>Fensu makes it executable:

Tests codify behavioral expectations.

Types codify interface expectations.

Fensu codifies architectural expectations.

A prompt or design doc can describe the intended structure. Only an executable rule<br>can tell you, deterministically and every time, when the repo has drifted from it.

What Fensu checks

Fensu is an architecture linter for Python repos. It analyzes your source and<br>reports faults , the places where the code has broken away from the architecture<br>you declared.<br>svg]:size-6" data-component-part="card-icon"><br>Layers and boundaries<br>Which modules and packages may import which. Absolute imports only, no star<br>imports, no reaching into a sibling’s internals, no importing from tooling at<br>runtime.

svg]:size-6" data-component-part="card-icon"><br>Module roles<br>What each kind of file may contain and where it may live. models.py holds<br>models, types.py holds types, main/ holds orchestrators, _helpers/ holds<br>phases, classes/ holds one class each.

svg]:size-6" data-component-part="card-icon"><br>Function shape<br>Size caps on orchestrators, explicit dataflow, keyword-only arguments,<br>mutate-only-if-returned, and no hidden control flow buried in comprehensions.

svg]:size-6" data-component-part="card-icon"><br>Naming contracts<br>Names that must mean what they claim. Validators raise or pass, predicates<br>return booleans, queries and conversions return values, and iterator names<br>produce iterators.

It also enforces test-suite conventions (mirrored layout, given-when-then naming,<br>dataclass-backed parametrization) and annotation conventions (annotate every<br>parameter and return, plus non-scalar local bindings) in the scopes where those<br>apply. See Rule families for the full set.<br>Fensu ships a coherent default architecture , not a blank canvas. You<br>adopt it and get a sensible starting point, then disable rules, tune thresholds,<br>activate a framework-specific native policy, or add your own rules deliberately<br>once you know what you are doing.<br>The default lays out code as domains built from a small set of roles.<br>A domain holds those roles directly, or splits into named subdomains that do:

src/my_package/<br>└── config/ # a domain<br>├── main/ # orchestrators and the public entry surface<br>├── _helpers/ # phase functions<br>├── classes/ # one class per module<br>├── models.py # data models<br>├── types.py # type declarations<br>├── constants.py<br>└── exceptions.py

That is the shipped default. See the architecture model<br>for the full layout. To adapt the defaults or encode conventions of your own, see<br>configuration and custom rules.

Enforce it, then see it

Fensu not only enforces repository structure, but also helps you navigate project<br>call flow.

fensu check stops the repo from losing its shape.

fensu map helps you see that shape again, as a deterministic<br>downstream or upstream call tree with clickable path:line locations.

fensu map run_map

fensu map works on any Python repository and does not require Fensu configuration.<br>It resolves calls it can prove and marks dynamic seams as unresolved rather than<br>guessing.

Keeping agents on the rails

Increasingly, the code that drifts is the code an agent wrote. Models are good at<br>local edits but not at preserving architecture over time. They tend to:

inline too much and grow functions;

smear state across boundaries;

add imports through the wrong layer;

satisfy the letter of a vague rule while violating its intent.

If you have to remind an agent of the same architectural rule repeatedly, that rule<br>should probably be executable. Fensu’s defaults target exactly these failure<br>modes, and fensu skills is the final piece: it generates agent<br>guidance from your active rules, and keeps them in sync automatically. This means that the rules...