Meet your code employees: the CodeNSM archetype taxonomy

Ask a good tech lead about a function and something interesting happens: they do not recite its cyclomatic complexity. They tell you what it is. "That's the router, everything goes through it." "That's just glue around the payment API." "Careful, that one's the auth check." The role comes first; the judgment follows from the role. A 2% error rate is alarming in a database read and unremarkable in a call to a flaky third-party API. Same number, different job, opposite verdict.

CodeNSM makes that instinct systematic. Every instrumented function is assigned — deterministically, from structure and runtime behaviour, never by an LLM's mood — to one of ten workplace archetypes. Think of it as walking into your codebase's office and finally reading everyone's badge. Here is the census.

The ten people who work in your codebase

• Project Manager — the routers and orchestrators. They own almost no logic themselves; they decide who does what. In our fleet telemetry they consistently carry a large multiple of their headcount share of call traffic, which is exactly why one sick Project Manager hurts more than ten sick specialists.
• Records Clerks — the readers and writers of your own database. High volume, and — a pattern our telemetry keeps confirming — among the safest roles in the building. Internal I/O is a solved problem; it is everything else that breaks.
• External Liaison — the diplomats who talk to third-party APIs. The boundary of your system is where the outside world's failures become yours, and this desk gets the worst of it: timeouts, rate limits, breaking changes made by strangers.
• Security & Compliance — authentication, authorization, permission gates. Very high footfall (every request passes the gate), near-zero tolerance for error, and disproportionate consequence when wrong.
• Specialist Engineer — the business logic. Pricing, scoring, matching, the algorithms that are the actual reason the company exists. Usually a minority of headcount; usually most of the unique engineering IP.
• Comms Runner — notifications, emails, webhooks out. Fire-and-forget by design, which is precisely why their failures go unnoticed longest.
• Facilities — cleanup, cron, cache eviction, housekeeping. Invisible until a janitor quits and the building slowly fills with garbage.
• Translator — serialization, parsing, format conversion. Rarely deep, always in the path, and a classic hiding place for silent data corruption.
• Floor Supervisor — logging, metrics, health checks. The watchmen. They should travel light; a slow Floor Supervisor is an organisational absurdity our state engine flags fast.
• Associate — the honest residual: generalists the classifier declines to force into a role. Keeping this bucket small is itself one of our pre-registered research hypotheses; a taxonomy that jams everything into "miscellaneous" has failed.

A job title tells you nothing about how someone's week is going

An archetype is a job description; a state is how the employee is doing this week. CodeNSM tracks live states with deliberately human names: Fit, Snoozing (present on payroll, doing nothing), Growing fat (accumulating weight and latency), Stressed (error rate climbing under load), Injury-prone (fragile in a load-bearing position — the debt that actually hurts), Quiet expert (low drama, high value, the function nobody thanks), and Top performer.

The names are not whimsy; they are compression. "Fragile-and-load-bearing intersection in the dependency graph" takes a paragraph to explain to a founder. "Your checkout flow has an injury-prone employee at a critical desk" takes one sentence, and the resulting conversation is the correct one. Peter Naur argued forty years ago that a program is really a theory held in developers' heads; the archetype layer is our attempt to give non-authors a working copy of that theory.

You do not manage 4,000 functions. You manage ten roles, seven states, and the handful of desks where they intersect badly.

What happens when you stop grading everyone on one curve

The practical payoff is comparative. Once every function has a role, health stops being graded on a single curve. External Liaisons are judged against External Liaisons — across your codebase and, for hosted customers, against the anonymized fleet. Melvin Conway observed in 1968 that systems mirror the organisations that build them; it turns out the mirror works in reverse, too — treating the codebase as an organisation gives you the entire management toolkit: headcount ratios, over-staffed departments, single points of failure, a payroll of Snoozing employees that Lehman's laws predict will only grow with age.

It also changes what "refactor" means. A team staring at a complexity report refactors the ugliest code. A team staring at the office view refactors the Injury-prone Project Manager first — because role times state times traffic is a priority, whereas ugliness is an aesthetic.

The part we keep in the vault

The role names, the states, and the reasoning above are public and will stay that way. The classification rules — which structural and behavioural signals assign a role, the thresholds that flip a state, the weights in the health roll-up — are the proprietary core of CodeNSM, refined against production telemetry that only we hold, and validated by a pre-registered research programme that only we ran. We tell you how to think about the taxonomy; the taxonomy engine itself is the product.

One disclosure we can make freely, because it is a result rather than a rule: the census is never what teams expect. In our fleet telemetry the typical codebase employs far more glue than its own engineers estimate, and the Specialist Engineers — the functions that justify the company's existence — are routinely outnumbered several-fold by Translators and Records Clerks. That gap between the org chart in the CTO's head and the one in production is, in a sentence, the product.

If you want to see your own org chart — every function badged, every desk lit up by live state — the install is one pip install and one init(). The first census usually takes about two minutes, and it is rarely the org chart people expected.