Software Architecture Metrics

1. 1Start with a minimal viable dashboard: a wiki page with the current value of each of the four key metrics, the definition of each metric and the time period it is calculated over, and the historical values. Flag the data sources so anyone can inspect them.
2. 2Publish the raw data, the calculations, and the headline figures together. Add the specific definitions your organization applies and how it treats edge cases. Nothing about the effort should be secret, and teams should be encouraged to read up on the four key metrics.
3. 3Put the display where the delivery teams will see it readily. They are the primary audience, because they are the people who will change the numbers. Prefer self-serve, real-time views scoped to each team's own pipelines.
4. 4Run recurring team discussions in three stages: first what each metric means, then why the numbers sit where they do (too high, too low, missing data), then how to improve them. Don't skip to stage three. Understanding builds the shared mental model.
5. 5Add trend lines, then the ability to view timescales longer than the default 31 days. Read the trend before the absolute value; for example, a rising mean time to discover is a proxy for whether people are learning from the past.
6. 6Expect team requests to escalate in a predictable order: process and cadence changes, then quality changes (pull tests left, more automation), then team-makeup changes (cross-functional or stream-aligned). Support each stage and let the change drive itself, accepting trade-offs and failures along the way.
7. 7Treat the architectural problems these changes expose as your agenda: looser-than-assumed coupling, blurry domain boundaries, frameworks that obstruct teams, hard-to-test modules, and microservices that cannot be observed under real traffic.
8. 8Be explicit with everyone about ownership changes that follow from the insights, including their technical and social trade-offs, so people don't lose focus or get frustrated.

The source describes an architect rolling out the four key metrics. Early team conversations were only about what each metric meant. Over the following weeks they moved to why the numbers were where they were (too high, too low, data missing), and then to how to improve them. Self-service, real-time data, a view limited to each team's own pipelines (all via PowerBI dashboards), trend lines, and timescales beyond 31 days all helped. The architect reports being amazed: problems that once fell to them alone to spot, understand, analyze, and remedy were now being raised and driven by the teams. The requests then escalated as predicted. First came "Can we change the cadence of releases?", then "Let's pull tests left" and "Let's add more automation", then "Can we move to cross-functional (or stream-aligned) teams?" All of it ended up exposing architectural problems such as coupling and observability gaps, which the architect then took on.

• If team conversations are still about what a metric means, then keep the forum going and hold off on improvement targets; understanding precedes action.
• If a team can only see an aggregate or other teams' data, then scope the view to its own pipelines and make it self-serve and real time.
• If a metric is skewed by manual capture (such as delayed change-failure tickets), then accept good-enough data, keep everything in the open, and use it to keep an eye on trends rather than police accuracy.
• If the team's requests move from process to quality to team structure, then treat that as a sign ownership is working and back it, rather than reasserting central control.
• If a change shifts component ownership, then state the technical and social consequences explicitly before it lands.

• Hiding or restricting the raw data and definitions. The tell: teams argue about whether the numbers are right, or never open the dashboard, and the metrics' greatest strength (sharing with everyone) is lost.
• Putting metrics where managers or architects look rather than where delivery teams look. The tell: the architect is still the only one who spots and analyzes problems.
• Going straight to improvement targets without building the mental model. The tell: discussions stay on the definition of a metric, or numbers are gamed.
• Fixating on the absolute value and ignoring the trend. The tell: nobody can say whether the team is learning from the past, for instance when mean time to discover creeps up.
• Changing ownership without explaining the trade-offs. The tell: people lose focus, get frustrated, and even leave the company.

• ▸Metric and definition: write each of the four key metrics with the exact definition and time period your organization uses.
• ▸Data sources: list where each number comes from so anyone can inspect it.
• ▸Access scope: state whether each team can self-serve real-time data limited to its own pipelines.
• ▸Display location: name where teams will see it readily (wiki page or dashboard).
• ▸Discussion stage: record whether the team is at meaning, why the numbers are where they are, or how to improve.
• ▸Trend view: note the timescale shown (default 31 days or longer) and whether trend lines are present.
• ▸Team requests so far: log requests as process, quality, or team-makeup changes.
• ▸Architectural problems exposed: list coupling, boundary, framework, testability, or observability issues found.
• ▸Ownership changes and trade-offs communicated: record who was told what about technical and social consequences.

1. 1Name the erosion you are measuring before you pick a tool. The passages define structural erosion (entropy) as a system drifting toward a 'big ball of mud': high coupling, undesirable dependencies between parts that should be unrelated, and many cyclic dependencies forming large cycle groups. Write that definition into the team's metric charter so every metric maps to a symptom.
2. 2Map your dependency graph at one consistent granularity (source files, namespaces, or packages) and identify cycle groups. A cycle group is a set of nodes bound by cyclic dependencies; nodes outside any cycle are clean. Record the number of cycle groups and the size of the largest one as your baseline.
3. 3Add a trend line, not just a snapshot. Re-run the same measurement on a regular schedule, because the passages say cycle groups grow continuously once they pass a certain size. A flat line is acceptable. A rising line signals erosion while the issue is still cheap to fix.
4. 4Turn each architectural rule into an automated fitness function in continuous integration. Examples: a no-cycles test between components, and an ArchUnit layer test that encodes the layered-architecture topology (who may access whom). The aim is that damaging code never enters the repository, with no reliance on code reviews or architecture review boards.
5. 5For a legacy system, start with lenient goals you can reach with reasonable effort. Strict standards applied on day one produce a flood of violations and hurt morale. Once the lenient goals are met, tighten them a step at a time.
6. 6Check that the system is still worth the effort. Improving metrics on a static codebase that is not in active development is, per the source, 'pretty useless'. Spend effort only where change is happening.
7. 7Build a regular rhythm of expansion followed by architecture improvement. Technical debt stays bounded only if the team is allowed to reduce it continuously. Reserve capacity every cycle for refactoring, not only when pain appears.
8. 8Decide between refactoring and replacing when costs leave the 'corridor of low and stable maintenance costs'. Refactoring brings the system back step by step from the inside. Replacement swaps in software with less debt. Use the shrinking functionality delivered per unit of time as your evidence.

The source cites Apache Cassandra as a real case of cycle-group growth. In version 2, the project already had a cycle group of about 450 Java files, and the passages note that such groups keep growing once they reach a certain size. Apply that to your own system: map the dependency graph at file or package level, highlight each cycle group, and record the size of the largest one. Re-measure each release. If it keeps growing, treat it as erosion, because a change in one area can now break something unrelated. Then add a cycle fitness function to CI so no new cycle can be committed, and set a lenient first goal, such as stopping growth, before you target shrinking the group. The passage on cost makes the stakes clear: as debt piles up, each change delivers less functionality per unit of time.

• If you inherit a legacy codebase with many metric violations, then set lenient, achievable goals first and tighten them after they are met, so developers are not overwhelmed.
• If a codebase is static and not in active development, then do not invest in improving its metrics, because the improvement has no payoff.
• If an architectural rule can be expressed as a test (no component cycles, layer access limits), then automate it as a fitness function in CI instead of relying on manual reviews that add delay.
• If delivered functionality per unit of time keeps falling and costs leave the low, stable corridor, then choose between step-by-step refactoring and replacement, and do not keep adding features on top of the debt.
• If a cycle group's size is growing across measurements, then treat it as active erosion and act immediately, since such groups keep growing once they reach a certain size.

• Measuring once instead of tracking trends. The tell: you have a one-off report but cannot say whether erosion is accelerating, so trouble is found only after it is expensive.
• Applying strict targets to a legacy system on day one. The tell: thousands of violations, developer morale falling, and the metrics being ignored.
• Governing structure by manual reviews and review boards alone. The tell: cyclic dependencies and layer violations still reach the repository, because checks are delayed or skipped under schedule pressure.
• Never allocating time for architecture improvement, only expansion. The tell: each change takes longer, bugs are harder to trace, and a change in one area breaks an unrelated one.
• Polishing metrics on a codebase nobody changes. The tell: the numbers improve while no business outcome moves.

• ▸System / module and granularity: name the system and state whether you analyze files, namespaces, or packages.
• ▸Baseline cycle groups: count of cycle groups and the size of the largest, with the date measured.
• ▸Latest measurement and trend: the same two numbers at the latest run, marked rising, flat, or falling.
• ▸Architectural rules to enforce: list the layer or dependency rules (e.g., no component cycles, layer access limits).
• ▸Automated fitness function per rule: the CI test that enforces each rule and whether it currently passes.
• ▸Current lenient goal: the achievable target for this period, stated as a number.
• ▸Next tightening step: the stricter goal you adopt once the current goal is met.
• ▸Still in active development?: yes or no; if no, note why metric work is skipped.
• ▸Refactor-or-replace signal: functionality delivered per unit of time now versus before, and the decision it supports.

1. 1Fix one scope before you measure anything. Decide whether you cover all software across the organization or only your program of work, and whether infrastructure changes are in or out. Apply the same scope to all four metrics: if infrastructure changes count in lead time and deployment frequency, infrastructure-induced outages count in change failure rate and time to restore.
2. 2Identify the right pipelines. Include only pipelines that listen for code and config changes in a source repository within your scope, run compilation, automated testing, and packaging, and deploy to production. Exclude CI tasks such as database backups.
3. 3Define the clock start for lead time. Use the commit or push timestamp. If changes sit on long-lived branches, you may use the merge-to-main pipeline trigger as a proxy, and you should record that choice as a known compromise.
4. 4Define the clock stop as the completion of the pipeline that performs the final production deployment. If QA does manual smoke testing and you want it counted, add a manual checkpoint at the end of the pipeline that QA presses once satisfied.
5. 5Compute total time to run as the elapsed time between clock start and clock stop. Decide up front how you will handle multistage and fan-in pipelines, since a single end-to-end pipeline is the easiest case.
6. 6Capture the stability pair from outage tracking. For change failure rate, record failures as a percentage of total deploys in the period. For time to restore service, measure from the failure to the delivered fix, including the time taken to become aware of it.
7. 7Visualize as time-series bar graphs with dates on the x-axis. Show deploys per day, mean lead time per day, failures per day, and restore time over a longer window (120 days versus 31). Co-plot the number of deploys on the lead time and failure graphs so the question 'was that a busy deploy day?' answers itself. Add a summary figure and a performance-band indicator for each metric.
8. 8Review the four metrics together in team conversations. Treat improvement in one metric that degrades another as unbalanced. Use the numbers to prompt discussion of architecture (testability, loose coupling, observability) rather than to dictate.

The chapter describes a home-built dashboard in Microsoft PowerBI, chosen because the client used Azure DevOps. Deployment frequency was a daily bar graph over 31 days, with a summary of average deploys per day, today's deploys, the period total, and mean and 95th-percentile trend lines. It was rated 'DORA Elite'. Lead time for changes showed the daily mean, highlighted the longest individual lead time, and shadow-plotted deploy counts in light gray because people kept asking whether many deploys had happened that day. It rated 'High' in the figure, though the text describes the highlight as 'Low' on the Elite-Low scale, so the source is inconsistent on that point. Change failure rate typically showed zero or one failure per 24 hours, so problems stood out immediately, and it was rated 'Elite'. Time to restore service used a 120-day window, co-plotted lead time, also showed zero open change failures, and rated 'High'. The team spent most time getting comfortable with time to restore service. Once deployment frequency and lead times were stable, it became their primary focus.

• If your scope includes infrastructure changes in any one metric, then include them in all four, including outages caused by infrastructure changes.
• If teams hold changes on long-lived branches, then use the merge-to-main pipeline trigger as a proxy commit timestamp, record it as a compromise, and revisit with trunk-based development or pair programming once the metrics are running.
• If a throughput metric improves while stability worsens, then treat it as unbalanced improvement and do not report it as a win.
• If lead time or failures spike on a given day, then check the co-plotted deploy count before investigating causes.
• If the metrics are in place and stable for throughput, then shift focus to time to restore service, as the team in the example did.

• Scope mismatch across metrics, such as counting infrastructure deploys but not infrastructure outages. The tell: change failure rate looks implausibly good next to a busy deploy count.
• Counting non-delivery pipelines, such as database backups, as deployments. The tell: deployment frequency is inflated and does not match real production releases.
• Optimizing one metric in isolation. The tell: deploys per day rise while failures or restore times worsen.
• Delaying measurement until the commit timestamp is perfect. The tell: no data exists because branch-based workflows make the start time hard to capture, when the merge-to-main proxy would already give useful signal.
• Using the metrics to dictate and control rather than to start conversations. The tell: teams game the numbers instead of discussing testability, coupling, and observability.

• ▸Scope: which software, programs, and whether infrastructure changes are included, applied identically to all four metrics.
• ▸Pipelines in scope: list each pipeline that deploys to production, and any CI tasks excluded.
• ▸Clock start: commit/push timestamp or merge-to-main proxy, with the reason if a proxy is used.
• ▸Clock stop: final production deployment pipeline completion, plus any manual QA checkpoint.
• ▸Multistage/fan-in handling: how total time to run is calculated for pipelines that fan in.
• ▸Failure definition: what counts as a change failure and an outage, including infrastructure-induced ones.
• ▸Restore measurement: how you timestamp failure awareness and fix delivery.
• ▸Dashboard windows: period per graph (e.g., 31 days for throughput, 120 days for restore) and co-plotted series.
• ▸Review cadence and owner: who discusses all four metrics together and when.

1. 1Fix the goal first. Agree with key stakeholders that maintainability is a priority quality goal, because the source says to spend effort only on attributes with a big impact on overall goals. Name it with the ISO/IEC 25010 subattributes: modularity, reusability, analyzability, modifiability, testability. Pick the two or three that hurt most in your system.
2. 2Define each fitness function with the mandatory categories from Table 2-2: breadth (atomic or holistic), trigger (triggered or continuous), execution location (CI/CD, test environment, production), metric type (true/false, discrete value, time series), automation (automated or manual), and quality attribute (maintainability). A metric with any category left blank is under-defined.
3. 3Add atomic checks for the code-level subattributes. The source's examples are cyclomatic complexity as an indication of maintainability and unit test coverage as an indication of maintainability and testability. Run them in CI. Treat a pass as evidence about that slice only, never about the whole system.
4. 4Add the optional categories where they matter. Set applicability per area, since the source's example is a different coverage type for JavaScript frontends than for Java backends. Mark each check temporary or permanent, and name the target audience (developers, product owners).
5. 5Add one holistic signal at the delivery level using the four key metrics: deployment frequency, lead time for changes, change failure rate, time to restore service. The first two measure throughput and the other two stability. Instrument four points: successful deployment counts, pipeline time per change, change-failure ticket counts, and ticket open duration.
6. 6Start manually. The source says manual capture is acceptable and is where it began each rollout. Publish a minimal viable dashboard on a wiki page with the current values, the definitions and time periods, the historical data, and links to the data sources. Put it where the delivering teams see it trivially; roll it up read-only for executives.
7. 7Use the numbers to start conversations, not to grade people. Watch for drift in either direction: complexity or coverage trending the wrong way, or lead time and restore time lengthening. Investigate the structural cause, such as accidental complexity from added dependencies, poorly documented or untested code, or unstructured design. Then change the architecture, not the target.

The source describes a monolith whose organization wants features to market faster, so it hires more people into product engineering teams. Each team tries its own solutions on top of the centralized architecture and adds accidental complexity: new dependencies, poorly documented or untested code, unstructured design. The result is a big ball of mud, and the ripple effects land on maintainability, operability, and changeability, so features slow down, the opposite of the intent. To keep this system in a stable maintenance-cost corridor, you would first agree with stakeholders that modifiability and testability are priority goals. Then you would add CI-triggered, automated, static fitness functions for cyclomatic complexity and unit test coverage, which are atomic and cover only the code they touch. Next you would add the four key metrics as a holistic view, captured manually at first and shown on a wiki-page dashboard. If lead time for changes lengthens while change failures rise, the atomic checks tell you where complexity is accumulating and the delivery metrics tell you it is hurting. In the source's own rollout, the team stabilized deployment frequency and lead time first, then made time to restore service the primary focus. Thresholds are yours to set; the passages give none for these checks.

• If a stakeholder cannot say why maintainability matters to a business goal, then do not build fitness functions for it yet; align quality goals first.
• If a metric passes but covers only part of the system (complexity, coverage), then record it as atomic and pair it with a holistic signal before claiming the system is maintainable.
• If you lack automation or a production environment, then capture manually and treat your highest shared environment (SIT, pre-prod, staging) as production, with testers and collaborating teams defining failures.
• If teams differ in technology or area, then scope each check with applicability instead of one global threshold.
• If delivery metrics worsen, then look for accidental complexity (new dependencies, untested or undocumented code, unstructured design) rather than asking for more headcount.

• Treating coverage or cyclomatic complexity as proof of whole-system maintainability. Tell: green dashboards while changes remain slow and risky.
• Defining only some fitness-function categories. Tell: nobody can say whether a check runs in CI or production, or who acts on it.
• Hiding the metrics from the teams who make the changes. Tell: only managers see the numbers and the engineers who could improve them never use them.
• Using a vague definition of failure, or one that shifts under pressure. Tell: change-failure counts change with whoever is reporting. The source's guidance is to pick a definition you are comfortable with, stay honest, and stick to it.
• Adding people and parallel solutions to a centralized system to go faster. Tell: growing dependencies and undocumented or untested code, and a distributed variant where understanding one business transaction exceeds cognitive capacity.

• ▸Priority subattribute: which of modularity, reusability, analyzability, modifiability, testability this serves, and the stakeholder goal behind it.
• ▸Metric and metric type: what is measured (e.g., cyclomatic complexity, unit test coverage, lead time for changes) and whether it is true/false, discrete, or time series.
• ▸Breadth: atomic or holistic, and what part of the system the result actually covers.
• ▸Trigger and location: triggered (CI, nightly) or continuous, and where it executes (CI/CD, test environment, production).
• ▸Automation: automated or manual, and who captures it if manual.
• ▸Applicability: the technology or area it covers (e.g., JavaScript frontend only, service A).
• ▸Permanence and audience: temporary or permanent, and who reads and acts on it.
• ▸Threshold and definition: the limit your team chose and the written definition of how it is calculated.
• ▸Response owner: who investigates when the threshold is breached, and what structural cause they check first.

1. 1Write down your definition of a 'failure in production' before you collect any data. Use the source's test: anything that makes a consumer unable, or even disinclined, to stay and finish the job they came to do. List what is in (outages, a 'working' system so slow that users drop out uncharacteristically) and what is out (cosmetic defects). Record that you accepted a judgment call, then stick to it.
2. 2Instrument the three raw data points: successful change deployments, the total time each change takes through the pipeline(s), and change-failure tickets. Open a ticket when a failure is spotted, which gives you a start time. Close it when service is restored, which gives you an end time. A failure no one spots is not counted, so make sure detection exists.
3. 3Close tickets on restoration, not on root cause. Rolling back so you are online and serving customers is a valid close. You are measuring service stability, and the root-cause fix is tracked elsewhere.
4. 4Calculate the four metrics from four data sets: deployment counts, pipeline run times per change, ticket counts, and ticket-open durations. Deployment frequency is successful deployments per time period (a day works well). With multiple pipelines, sum them. Do this by hand first if you have to. Manual capture is acceptable and the author starts there.
5. 5If you have no production yet, name your 'highest environment' (SIT, pre-prod, or staging): the shared one closest to production, where accepting a change means no more work remains before the final step. Treat testers and collaborating teams as the users who define service failures, and treat test failures as seriously as real ones.
6. 6Publish a minimal viable dashboard (a wiki page): current value of each metric, each metric's definition and calculation period, historical values, and links to the data sources. Make the raw data, the calculations, and the definitions available alongside the headline figures.
7. 7Aim the display at the delivery teams. They must be able to see and drill into the data for their own services trivially. Give executives a rolled-up, read-only view and let them ask for more detail.
8. 8Use the metrics to start conversations, not to grade teams. Add trend lines and timescales longer than the default window. When failure and restore numbers worsen, treat it as a prompt to look for architectural causes: coupling, unclear domain boundaries, hard-to-test modules, services that cannot be observed in production.

Andrew Harmel-Law's rollout shows the progression. His teams got PowerBI dashboards that let them self-serve data in real time and see only the data from their own pipelines. Trend lines were added, followed by timescales longer than the default 31 days. The cross-functional discussions that followed surprised him. Problems that once fell to him alone as architect to spot, analyze and fix were now being raised and solved by the teams. The requests came in a consistent order. First were process changes ('Can we change the cadence of releases?'). Next were quality changes ('Let's pull tests left', 'Let's add more automation'). Then came team-makeup changes ('Can we move to cross-functional or stream-aligned teams?'). All of it ended by exposing architectural problems: coupling looser on paper than in practice, domain boundaries less crisp than drawn, frameworks that got in the way, modules hard to test, and microservices impossible to observe under real traffic. The business-facing signal sits in the failure definition. Users who drop out of a slow system count as a service failure, so a user-visible quality problem shows up in the numbers.

• If a problem makes users unable or disinclined to finish their task, it is a service failure and gets a ticket. If it is purely cosmetic, it does not.
• If service is restored by rollback, close the ticket. Track the root-cause fix separately so restore-time stays an honest stability measure.
• If you are not deploying to production, define the highest environment and treat it as production, with testers and partner teams as the users who define failure.
• If you cannot automate capture yet, count and calculate manually. A transparent manual baseline beats a delayed automated one.
• If executives ask for more detail, point them to the shared data and calculations rather than building a separate view. If a team's numbers stall, ask which architectural property (testability, coupling, observability) is blocking them.

• Defining failure so narrowly that only outages count. The tell is that user dropout from a slow-but-up system never produces a ticket, and the numbers look healthy while users leave.
• Closing tickets only after the root cause is fixed. The tell is inflated time-to-restore and teams reluctant to roll back.
• Keeping the metrics in a management-only report. The tell is that teams cannot find their own service's numbers and no team-initiated improvement requests appear.
• Hiding definitions and raw data behind headline figures. The tell is arguments about what a number means instead of what to change.
• Reading the metrics as a scorecard rather than a conversation starter. The tell is that the architect still solves every problem alone, and teams never ask for changes to cadence, testing, or team makeup.

• ▸Failure definition: write the sentence that says what makes a consumer unable or disinclined to finish their job.
• ▸Explicitly excluded items: list what does not count (e.g., cosmetic defects).
• ▸Detection source: name how failures are spotted (monitoring, user report, tester) so none go unrecorded.
• ▸Ticket open rule: state who opens a change-failure ticket and when, since this sets the start time.
• ▸Ticket close rule: state that closing happens on service restoration (rollback allowed), not on root cause.
• ▸Environment measured: production, or the named 'highest environment' with its testers and teams as users.
• ▸Calculation period: state the window (e.g., per day for deployment frequency; default trend window) and how multiple pipelines are summed.
• ▸Data and definition links: give the URLs of raw data, calculations, and this sheet on the dashboard page.
• ▸Audience and access: list the teams with drill-down access and the roll-up, read-only view for executives.

1. 1Define the fitness function at design time as three linked parts: the target metric, its context, and the threshold. Write it in the passage's form, for example 'Unit Test Coverage > 0.9; Execute on each CI Build; Fail when below target coverage'. The architectural test comes afterward and is not part of the definition.
2. 2Name the context fields explicitly: what the test checks, when it runs (each CI build, nightly integration build, continuously without a trigger), where it runs (CI/CD host, test system such as performance or load, production), and the metric type (true/false, numeric, or time series).
3. 3Write the architectural test so it produces the metric automatically and, where possible, asserts the threshold itself. Make it distinct from a functional test: not 'can I create a customer' but 'can I create 10 customers within 10 milliseconds'.
4. 4Wire each test into the pipeline that matches its cadence. Fast checks, such as unit coverage, run on every CI build and fail the build. Slower ones, such as integration coverage at 50%, run on the nightly integration build.
5. 5For delivery metrics, fix one scope first (all organization changes, one program, or one product, with or without infrastructure changes). Apply the same scope to all four key metrics: if infrastructure changes count in lead time and deployment frequency, infrastructure-induced outages count too.
6. 6Instrument three raw data points: a pipeline start, a deploy-to-production event, and a change-failure ticket. Include only pipelines that listen for code and config changes and deploy to production, and exclude tasks like database backups. Count only successful runs that deploy service updates to users.
7. 7Define 'failure in production' in writing before you collect data, and record failures via a change-failure ticket. Opening starts a clock and closing, when service is restored (a rollback is acceptable), stops it. If you have no production, name a 'highest environment' (SIT, pre-prod, staging) and treat testers as users.
8. 8Start by capturing manually if automation is not ready. Automate afterward, and store numeric results as a time series when the trend is the valuable output.

The passages give two fitness functions for a hypothetical system. Example 2-1 is 'Unit Test Coverage > 0.9; Execute on each CI Build; Fail when below target coverage'. Example 2-2 is 'Integration Test Coverage > 0.5; Execute on each nightly integration test build; Fail when below target coverage'. Each names a metric (coverage), a threshold (0.9, 0.5), a trigger (every CI build, nightly build), and a consequence (fail). A developer pushes a change, the CI build computes unit coverage, and the build fails if it drops below 90%. That evaluates the quality on every change instead of at a late review. The slower integration tests run nightly, so the 50% check is frequent but cheaper. An architectural example from the same source: instead of only checking that a customer can be created, the test creates 10 customers and verifies it took under 10 milliseconds. The delivery side works the same way. A pipeline run that fails at compilation is excluded, because counting it would shorten lead time artificially.

• If a test is cheap and fast, run it on every CI build and fail the build. If it is slow or needs heavy environments, run it nightly or in a performance/load test system, and state that trigger in the fitness function.
• If automating a check costs too much or is not feasible (the passage's example is a legal-requirements test), run it manually and keep it as a fitness function anyway. Automation is preferred but not required.
• If you have no production environment, define the highest shared environment closest to production and treat its test failures as real service failures. Do not skip measuring.
• If a pipeline run fails before deploying (for example at compilation), exclude it from lead time. Count only runs that deploy service updates to users.
• If your scope for one of the four metrics changes, change it for all four, or the figures are not comparable.

• Counting failed or non-deploying builds: lead times look artificially short and deployment frequency inflates. The tell: very fast 'builds' dominate the data and lead time improves with no real change.
• Mismatched scope across the four metrics, for example infrastructure changes in lead time but infrastructure outages missing from failure counts. The tell: change failure rate looks implausibly low against change volume.
• Defining the fitness function and test in one step, so the goal bends to whatever is easy to implement. The tell: thresholds mirror what the tool already outputs, not a stated quality goal.
• Vague failure definitions: counting cosmetic defects, or missing slow-but-technically-up service that makes users disinclined to stay. The tell: arguments about whether each incident 'counts'.
• Delaying measurement until automation exists, or including non-delivery pipelines such as database backups. The tell: no data after weeks of tooling work, or noisy pipeline counts.

• ▸Quality attribute / goal: which quality goal does this measure (e.g., performance, maintainability)?
• ▸Target metric: what value is produced, and is it true/false, numeric, or time series?
• ▸Threshold and direction: the value to stay above or below (e.g., > 0.9, within 10 ms).
• ▸Trigger: each CI build, nightly integration build, or continuous without trigger?
• ▸Execution environment: CI/CD host, test system (performance/load), or production?
• ▸Consequence: fail the build, alert, or record only?
• ▸Automated or manual: if manual, why (cost, feasibility)?
• ▸Scope: which repositories, pipelines, and change types (software, infrastructure) are included?
• ▸Failure definition and clocks: what counts as a service failure, where the ticket opens and closes, and the highest environment if not in production.

1. 1Start from the five attributes, not from a tool. Write each one as a one-line check for your system: modularity (parts change without forcing change elsewhere), cohesion (things that change together sit together), separation of concerns (each part solves one problem), abstraction/information hiding (seams let you consume behavior without knowing internals), coupling (how much separate parts must change together).
2. 2Anchor the effort to quality goals. Align with key stakeholders on which ISO/IEC 25010 attributes matter (Maintainability lists modularity, reusability, analyzability, modifiability, testability). Spend measurement effort only on attributes that have a big impact on those goals.
3. 3Express the goal as a fitness function: an objective function that summarizes how close the design is to the aim, outputting a discrete value (the metric). Define the verification mechanism that produces it. Automate it if you can, but automation is not required.
4. 4Test the seams with a swap scenario. Pick a concrete change, such as replacing an RDBMS-backed repository with a GraphDB repository. Ask whether the domain core is separated from persistence. If the two are conflated, you have found a coupling problem.
5. 5Use testability as the probe. For one module, check whether you can reach the relevant parts, put them in a well-defined state, invoke behavior, and capture responses. If setup is hard, the module is probably not cohesive or is tightly coupled to others.
6. 6Check the tests themselves. If tests are decoupled from the code, the code can change without forcing test changes. Tests that break on internal changes show leaky abstractions. Tests that can target an abstraction boundary show a usable seam.
7. 7For a whole codebase or an IT landscape, assess technical debt with the modularity maturity index (MMI). Use the result to decide which systems to refactor, which to replace, and which to leave alone.
8. 8Feed delivery signals back into the architecture. Review the four key metrics (deployment frequency, lead time for changes, change failure rate, time to restore service) with the team weekly. Treat the coupling that is looser on paper than in practice, and the domain boundaries that are less crisp than they looked, as the architectural problems the metrics expose.

The source's own example is the database swap. Suppose you learn that your system would run more efficiently on a graph database than on a relational one. If you separated the core domain logic from the persistence of its results early on, you can imagine unplugging the RDBMS-backed repository and plugging in a GraphDB repository with relative ease. That outcome shows good separation of concerns, better modularity and cohesion, and decent abstraction. If core domain and persistence are conflated, the same move is very hard even to contemplate. You can turn this into a fitness function: define the aim as 'persistence replaceable without changing domain logic', and verify it by trying to write a domain test with no database present. The passages give no figures for this scenario, so treat the pass/fail result as your discrete metric. A second signal comes from delivery data. When teams discuss the four key metrics weekly, they surface coupling that isn't as loose as expected and domain boundaries that aren't as crisp as they appeared. Those findings point you to the modules to restructure.

• If a module is hard to set up for a test, then suspect low cohesion or tight coupling to other modules before blaming the test tooling.
• If a planned technology change (for example, a different database) would force changes in domain logic, then introduce a seam such as a repository abstraction before committing to the change.
• If a quality attribute has little impact on your overall goals, then do not define a fitness function for it. Spend effort on the attributes stakeholders rank highest.
• If tests break whenever implementation details change, then strengthen the abstraction so tests target the boundary rather than the internals.
• If an MMI-style assessment shows heavy technical debt in one system and little in another, then refactor or replace the first and leave the second alone.

• Treating modularity as a diagram property only. The tell: the whiteboard looks clean, yet production reveals coupling looser on paper than in the code or domain boundaries that are not crisp.
• Conflating domain logic with persistence. The tell: a change to the data store forces edits throughout the core, so a swap like RDBMS to GraphDB is unthinkable.
• Measuring everything. The tell: many metrics defined for attributes that do not connect to stakeholder quality goals, and no one acts on them.
• Leaky abstractions. The tell: consumers need to understand how another part works internally, and tests must change whenever internals change.
• Architect as sole owner of structural health. The tell: problems fall to one person to spot, analyze, and remedy while teams do not discuss or act on the metrics.

• ▸Module or component under review: name the boundary you are assessing.
• ▸Quality goal it serves: cite the stakeholder-agreed ISO 25010 attribute (e.g., modifiability, testability).
• ▸Single concern: state in one sentence the one problem this module solves; if you need 'and', note the mix.
• ▸Things that change together: list code that changes together and whether it sits together (cohesion).
• ▸Hidden implementation: list what consumers must not need to know; note any leaks.
• ▸Coupled-change partners: list the other parts that must change when this one changes.
• ▸Swap scenario: describe one realistic replacement (e.g., repository backend) and whether it can be done without touching domain logic.
• ▸Test setup effort: record how hard it is to reach, set up, invoke, and capture responses for this module in isolation.
• ▸Fitness function and result: define the objective check, how it is verified, and its discrete value this review.

1. 1Pick the metrics and thresholds the passages support: Modified Cyclomatic Complexity ≤ 15 per method (soft), maximum indentation ≤ 4 per method (soft), and source file size ≤ 800 Lines of Code (soft). Write them down as team rules before you measure anything.
2. 2Choose the cyclomatic variant on purpose. Modified Cyclomatic Complexity adds only 1 per switch statement, because switches inflate the plain metric without adding real complexity. Extended Cyclomatic Complexity adds 1 per && and || because short-circuiting acts like an extra conditional. Pick one variant and use it everywhere.
3. 3Aggregate upward with a weighted average. For classes, packages, and files, use Average Cyclomatic Complexity and average indentation, both weighted by Number of Statements, so many small getters and setters do not dilute a few long methods.
4. 4Define a 'complex file' in one sentence: average indentation over 3, or average complexity over 10, or size over 800 LoC. Sum the Lines of Code of those files and divide by total system LoC. Set a ceiling, for example no more than 10% of code complex.
5. 5Add change history to find where complexity hurts. Use Number of Changes (d) per file over a d-day window from version control, as in Tornhill's approach. Frequent change signals design instability. Cross it with the complexity list and refactor files that are both complex and frequently changed first.
6. 6Automate it as an atomic, triggered fitness function in the CI build. This is the cheap bottom layer of the pyramid. Break the build when a rule is violated. Do not create more checks than you need, because each adds overhead.
7. 7Track the metrics once a day in an automated build and chart the trend (for example, Lines of Code over the last 90 days). Use the chart to catch harmful trends early, before a hard threshold fails.
8. 8Roll the same rules out across the organization so every developer meets the same limits.

The source gives a ready-made fitness function. Define a file as complex if average indentation exceeds 3, or average complexity exceeds 10, or size exceeds 800 LoC. Say your system has a certain total LoC. Sum the LoC of every file that trips any of the three tests, divide by the system total, and compare against a 10% ceiling. The daily CI build computes this and breaks if the ratio exceeds 10%. The same build stores the number so you can chart it over 90 days. Per-method soft limits (indentation 4, Modified Cyclomatic Complexity 15) sit alongside it. Because the average is weighted by Number of Statements, a file with fifty trivial getters and one 120-statement method with deep nesting still shows as complex. Then pull the Number of Changes (d) for the flagged files and start refactoring with the ones that change most often.

• If a method has many switch branches but is otherwise flat, then use Modified Cyclomatic Complexity (switch counts 1) rather than the plain metric, to avoid false alarms.
• If the code is full of short-circuit && and || conditions, then use Extended Cyclomatic Complexity, because each one behaves like an extra conditional.
• If a file is complex and also changes often (high Number of Changes (d)), then refactor it before complex files that rarely change.
• If you aggregate to class or file level, then weight by Number of Statements, never a plain average, so small getters and setters cannot mask long methods.
• If a threshold is soft and you are tempted to hard-block on it, then chart the trend first and break the build only once the team has absorbed the rule; a rising Lines of Code or complexity trend is a signal even before a limit is crossed.

• Plain-averaging complexity across a class: the tell is a class with dozens of trivial accessors reporting a low average while one method is a tangle. Fix by weighting with Number of Statements.
• Treating the plain cyclomatic number of a big switch as a defect: the tell is endless flagged dispatch methods that are easy to read. Switch to the Modified variant.
• Measuring once and never trending: the tell is a one-off report and no chart, so growth in LoC or complexity goes unnoticed until the build is hard to change. Gather daily and plot.
• Creating too many metric checks in the base layer: the tell is a pipeline cluttered with overlapping checks that nobody maintains. Keep only checks that give value, since each adds overhead.
• Refactoring by complexity alone, ignoring change history: the tell is effort spent on stable, ugly files that nobody touches. Cross with Number of Changes (d) to find hotspots.

• ▸Cyclomatic variant: choose plain, Modified (switch = 1), or Extended (adds && and ||).
• ▸Method limits: write max Cyclomatic Complexity (source: 15) and max indentation (source: 4).
• ▸File size limit: write the soft LoC cap (source: 800).
• ▸Complex-file definition: set average indentation, average complexity, and LoC cutoffs (source example: 3, 10, 800).
• ▸Aggregation weight: confirm Number of Statements is the weight for all averages.
• ▸Complex-code ceiling: set the max share of total LoC in complex files (source example: 10%).
• ▸Change-history window: set d in days for Number of Changes (d).
• ▸Hotspot list: name files that are both complex and frequently changed, in refactor order.
• ▸CI action and trend: state whether the build breaks or warns, and where the daily chart is kept.

1. 1Treat testability as a design driver, not a QA activity. Write the test first or alongside the code, and let the test define the boundary of the unit. The passages say boundaries you can test are boundaries that limit the scope and complexity of your tests, and the same attributes make code easy to change.
2. 2Define releasability as the pipeline's verdict. Set the pipeline scope as 'from commit to releasable outcome.' If a candidate passes every stage, it is fit for release with no more work to do.
3. 3Audit for post-pipeline testing. If anyone must test components or subsystems together with other parts after the pipeline ends, the pipeline does not determine releasability. Move those checks inside the pipeline or redraw the unit so it can be evaluated on its own.
4. 4Give each independently releasable artifact its own pipeline. One pipeline per artifact is the microservices tenet of independent deployability. Accept the coordination cost if you pick this route.
5. 5Classify each fitness function on three axes: atomic or holistic (how much of the system is exercised), triggered or continual (CI run, nightly schedule, or constant production monitoring), and where it executes (test system, production, or CI/CD pipeline). Build atomic checks first (cyclomatic complexity, unit test coverage) and add holistic ones where end-user behavior matters, knowing they cost more to build and maintain.
6. 6Add a deployment-level reliability test. Verify the system stays operational during a rolling update, providing zero downtime, and that it stays responsive if a node is down.
7. 7Track delivery with the four key metrics. Source the three raw data points from the change-to-running-system flow. Count only change-triggered pipelines (time-triggered ones with no change produce no deployment). Collect all builds without cherry-picking, state your estimation accuracy, and use daily totals rather than averaging averages.
8. 8Use the metrics to start conversations with team members and move gradually toward a more testable, modular, fault-tolerant, runnable, and observable architecture.

Take the zero-downtime check described in the passages. A team has a service with its own pipeline. Their reliability fitness function runs a rolling update against the system in a test environment while traffic is applied, and verifies the system stays operational and no requests fail. It is holistic, because a pass means a large part of the system works for end users. It is triggered by the CI/CD pipeline on each change. A pass becomes part of the pipeline's definition of releasable. The team also deliberately takes one node down during the test to show the whole system stays responsive. Alongside it they run atomic checks, such as unit test coverage and cyclomatic complexity, as cheap early feedback. They feed pipeline results into the four key metrics, ignoring scheduled runs with no change and using daily totals for the graph. If a release manager still wants a separate integration pass after the pipeline, the pipeline has failed to define releasability, and the check moves into it.

• If a pipeline passes but someone still needs broader testing with other components before release, then the unit boundary or pipeline scope is wrong: move those tests into the pipeline or redraw the boundary.
• If a component is hard to test in isolation, then treat it as a design defect (poor modularity or coupling) and fix the design, not the test.
• If you need fast, cheap feedback on maintainability or testability, then use atomic fitness functions (complexity, coverage); if you need confidence that users can use the system as intended, then invest in a holistic one despite its upkeep.
• If a metric is about real-world behavior such as response time, then run it continually against production monitoring; if it guards a change, then trigger it in CI.
• If a pipeline run was triggered by time rather than change, then exclude it from the four key metrics, because it produces no deployment.

• Declaring 'done' at pipeline pass while a separate manual or cross-system test phase remains. The tell: releases wait on a stage outside the pipeline, or a change-advisory-board-style approval is needed.
• Reading coverage or complexity numbers as whole-system health. The tell: atomic checks are green yet users hit failures, because a positive atomic result only speaks for a limited part.
• Writing tests after the code, so the design is never shaped by them. The tell: tests need heavy setup and large scopes to run.
• Cherry-picking builds or averaging averages in the delivery metrics. The tell: the dashboard looks smooth but does not match the team's experience; figures carry no stated accuracy.
• Counting time-triggered pipeline runs as deployments. The tell: deployment frequency rises while nothing has changed.

• ▸Unit under review: name the component or service you are assessing.
• ▸Independent pipeline? Yes or no: does this artifact have its own commit-to-release pipeline?
• ▸Pipeline scope: list the stages from commit to releasable outcome.
• ▸Post-pipeline testing: list any test or approval still required after the pipeline passes.
• ▸Fitness function name: state the check being defined.
• ▸Atomic or holistic: say how much of the system the check exercises.
• ▸Trigger: CI on change, scheduled run, or continual in production.
• ▸Execution environment: test system, production, or CI/CD pipeline.
• ▸Isolation difficulty: note what makes the unit hard to test alone, and the design change that would fix it.
• ▸Metric data quality: record the estimated accuracy of the builds and data points collected.

1. 1Name the goal before the metric. Write one sentence stating the architectural outcome you want (the passages' example: 'more testable, decoupled, fault-tolerant, cloud native, runnable, and observable architecture') and the business outcome it serves (YourFinFreedom's goal of being a major player across the European Union). A metric with no goal sentence above it does not get collected.
2. 2Choose a metric set whose members constrain each other. Pair throughput (deployment frequency, lead time for changes) with stability (change failure rate, time to restore service). Improving one element while ignoring its partner is the failure this pairing exists to expose.
3. 3Draw the mental model before you read any numbers. Sketch the pipeline from a developer pushing changes to version control through to the change running in the live service. Mark where each metric starts and stops, so lead time for changes is not confused with lean lead time, which includes writing the code and may start at the product manager's idea.
4. 4Define every term in writing before collecting data. Decide what counts as a 'failure' (something that stops users getting their tasks done), which builds count (all of them, no cherry-picking), and what to exclude (time-triggered pipelines that carry no change). Start with manual tickets as the failure signal if monitoring cannot yet supply timestamps, and record the known inaccuracy.
5. 5State your accuracy honestly. If you estimate a figure, record the degree of accuracy. Avoid averaging averages: keep daily totals and compute from those. Treat unresolved failures as a data gap, since they have no 'resolved' timestamp.
6. 6Make the data self-serve and scoped. Give each team real-time access to only its own pipelines' data, with trend lines and timescales beyond the default 31 days. Teams that can see their numbers can interrogate them.
7. 7Run a weekly cadence that moves through three questions in order: what does each metric mean, why are the numbers where they are (too high, too low, missing data), and how do we improve them. Review upcoming spikes and ADRs in the same session so goals and decisions stay linked.
8. 8Before an experiment that costs capacity, communicate the consequences, the intended outcome, and the link to the organizational goal to sponsors. Then share the results, as Anna does with Keisha and the stakeholders. Re-check periodically whether the current metrics still fit the goals.

Anna, an architect at YourFinFreedom, wants to use leverage points in the architecture to reduce complexity in the Travel Insurance domain. She runs workshops, builds a KPI Value Tree, and gets a plan from the product engineering team. She knows the team's capacity to deliver features will drop during the experiment, so she meets Keisha and shares the workshop outcomes, the value tree, and the plan. She names the consequences, what she wants to learn, and how it contributes to the company goal of being a major EU player. Keisha backs her, and the stakeholders accept the honest framing and agree the experiment should run and its results be shared. The team takes the travel insurance policy service live and replaces the central customer information service for that domain. The metrics show the old boundaries were misplaced, and redefining them means the domain's services no longer need release orchestration. Because goals and expected costs were agreed up front, the stakeholders back the same approach in other domains. Later, as the domain's KPIs improve, leaders question whether current metrics such as 'Decrease the time to find a match for the insurance quote request' still fit, since analysts forecast a need to hire more people. That is a goal-clarity check on the metrics themselves.

• If a proposed metric cannot be traced to a written goal sentence, then drop it or do not collect it yet.
• If one half of the throughput/stability pair is improving while the other degrades, then treat it as a signal about the system, not a win, and discuss it at the weekly review.
• If the team cannot yet say what a metric means, then spend the cadence on definitions before discussing causes or improvements.
• If accurate failure timing needs tooling you lack, then start with manual tickets, record the inaccuracy, and refine later.
• If a KPI is stable and meets current needs but forecasts point to growth pressure (e.g., hiring to cope with quote matching), then re-examine whether the KPI still reflects the goal.

• Metrics chosen because they are easy to collect rather than tied to a goal. Tell: nobody can state what decision a number informs.
• Confusing lead time for changes with lean lead time. Tell: the clock starts at the idea or at coding, and the numbers cannot be compared with others' four-key figures.
• Cherry-picking builds or averaging averages. Tell: the numbers look healthy but do not match team experience, or daily figures disagree with the aggregate.
• Presenting metrics to teams without the model behind them. Tell: discussions stay on 'what does this mean' and never reach why and how to improve.
• Running a costly experiment without managing expectations. Tell: stakeholders are surprised by reduced feature capacity and withdraw support.

• ▸Business goal: one sentence naming the organizational outcome the work serves.
• ▸Architectural goal: the quality attributes you want (e.g., testable, decoupled, observable).
• ▸Metric name: which measure will tell you if the goal is moving.
• ▸Definition and boundaries: where measurement starts and stops, what counts, what is excluded (e.g., time-triggered pipelines).
• ▸Failure definition: what counts as a failure for stability metrics, in terms of users unable to complete tasks.
• ▸Data source and accuracy: where the data comes from (e.g., manual tickets) and your honest estimate of its accuracy.
• ▸Paired counter-metric: the metric that would reveal a harmful trade-off if this one improves.
• ▸Owner and cadence: who reviews it, how often, and what weekly questions (meaning, why, improve) apply.
• ▸Review trigger: the condition under which you re-check whether this metric still fits the goal.