Agent guidance: fundamentals-x

This directory holds Fundamentals series posts. Hugo-wide rules (front matter baseline, cover images, internal/external linking) are in hugo/AGENTS.md at the site root—follow those for every post, then apply the series rules below.

Titles, slugs, and folders

  • Title (default for new posts): Use Fundamentals of [Topic] (natural Title Case—for example Fundamentals of Software Automation, Fundamentals of CI/CD and Release Engineering).
  • Slug and directory: Prefer fundamentals-of-<topic-in-kebab-case> so slug, the folder name, and the last segment of url stay aligned.
  • Legacy exception: A few posts use the fundamental-<topic> folder/slug pattern with titles like Fundamental [Topic] (for example Fundamental Software Concepts, Fundamental Algorithmic Patterns). Do not rename those silently; new work should follow fundamentals-of-* + Fundamentals of … unless there is a deliberate reason to align with the legacy pattern.

Front matter (series-specific)

In addition to hugo/AGENTS.md:

  • categories: Lead with Fundamentals, then one or two topical categories (for example Software Engineering, DevOps) consistent with sibling posts.
  • series: Fundamentals: Set for long-form series explainers when it matches neighboring articles (some reference-style pages omit it—follow the closest comparable post).
  • diataxis: Set when the post fits the site’s Diataxis labeling (often explanation for understanding-oriented fundamentals; use reference or how-to when the article is catalog- or procedure-shaped). Match comparable posts in this directory.

Body structure and voice

  • Prefer a clear introduction that states what the article covers and who it is for.
  • For long explainers, use Prerequisites & Audience, Jump to (anchor links), and TL;DR when similar articles in this folder do.
  • Include the Laws, bias, and fallacies section required for this series (see the dedicated heading below).
  • Include a References section: authoritative external links plus internal cross-links to related fundamentals posts (use the ref shortcode with the target post’s slug only, as in hugo/AGENTS.md).
  • Use Diataxis-style callouts in prose when the rest of the series does (for example a short “Type: Explanation …” line).

Laws, bias, and fallacies (required)

Always include a dedicated section (for example ## Laws, bias, and fallacies or a title that fits the article tone) that ties the topic to how people and organizations actually reason and decide.

  • Laws and named principles: Name a few relevant laws, heuristics, or named effects (for example industry adages, “X’s law,” Goodhart-style dynamics, Brooks, Conway, etc.—whatever genuinely fits the subject). For each, give a one-line gist and how it shows up in this article’s domain (teams, tooling, metrics, process).
  • Bias: Call out cognitive biases that commonly distort thinking about this topic (confirmation bias, sunk cost, availability, planning fallacy, automation complacency—only what applies). Explain what goes wrong and what to do instead in context.
  • Fallacies: Mention logical or rhetorical fallacies that often appear in arguments about this topic (false dichotomy, appeal to novelty, moving goalposts—again, only what applies). Tie each to a concrete scenario readers might recognize.

Keep the section practical, not a philosophy catalog: every item should answer “so what for someone working in this space?” Order and depth should match article length—short posts get a tight subset; long explainers can use subheadings or the cards shortcode if comparisons would otherwise become tables (per hugo/AGENTS.md).

Glossary (required)

Always render article glossary terms with the shared shortcode and data file—do not hand-maintain duplicate glossary blocks in Markdown when the terms exist (or should exist) in the canonical glossary.

  • Shortcode: hugo/layouts/shortcodes/glossary.html
  • Data: hugo/data/a-software-fundamentals-glossary.jsonc (JSON array of objects: term, definition, subject; optional source)

Each entry’s subject is a slug string (for example ci-cd-and-release-engineering, software-development-operations, maintainability). Pass that exact value as subject so only rows for that article’s theme are emitted.

  • Use subject="all" only when you intentionally want every glossary entry, grouped by subject (rare for a single article).

Example for LLMs

Replace YOUR_SUBJECT_SLUG with the subject value from the JSONC entries this article should show (must match character-for-character).

## Glossary

Concrete example (maintainability terms only):

## Glossary


Abstraction: Removing physical, spatial, or temporal detail to focus on essentials. In code, hiding implementation behind interfaces so callers depend on behavior, not structure.
Afferent coupling: The number of modules that depend on a given module. High afferent coupling means many callers; changes ripple widely.
Code smell: A surface indication that code may have a design or maintainability problem. Suggests refactoring rather than a bug per se.
Cohesion: How closely the responsibilities of a module hang together. High cohesion means one clear purpose; low cohesion (e.g. a "utility" doing unrelated things) hurts maintainability.
Coupling: The degree to which modules depend on each other. Low coupling keeps changes local; high coupling makes changes ripple and tests harder.
Cyclomatic complexity: The number of linearly independent paths through code. Calculated from branches, loops, and conditionals.
Efferent coupling: The number of modules a given module depends on. High efferent coupling means many dependencies; the module is rigid.
Feature envy: A code smell where a method uses another object's data more than its own. Suggests the logic may belong in the other object.
God class: A class with excessive size (500+ lines) and many responsibilities. Hard to understand and change.
Refactoring: Changing the internal structure of code without changing its external behavior. Improves design and maintainability while preserving semantics.
Shotgun surgery: A code smell where one change requires edits in many files. Indicates scattered related logic.
Software maintenance: Modification of a software product after delivery to correct faults, improve performance, or adapt to a changed environment.
Technical debt: Deferred work that makes future changes harder. The metaphor: quick-and-dirty code "borrows" time and "pays interest" on every change.

If a term readers need is missing or the wrong subject is used, add or adjust entries in a-software-fundamentals-glossary.jsonc and choose the subject slug that matches this article’s glossary section—do not fork definitions only in the post body.