How this
reference
is built.

Most software writing on the internet is one of these: shallow inspiration, blog-post opinion, tool marketing, or fragmented best practices.

The Hard Parts is not any of those. It is a reference system: a catalog of named patterns you can look up the way you'd look up an entry in a field guide. Entries are structured, cross-linked, and intended to be revisited repeatedly, not consumed once.

The stance is deliberately anti-dogmatic. Software work is contextual; trade-offs are real; patterns repeat. Naming them lets people act earlier and argue better.

The site is organised around four complementary categories. Each has its own voice, its own metadata ladders, and its own signature section on the detail page.

• FM Failure Modes Named failure patterns in software work - how they start, how they escalate, and what good responses look like. 31
• TD Tech Decisions Structured trade-off references for consequential engineering decisions. Two options side-by-side, honest about what's lost on each side. 38
• RF Red Flags Early-warning signals across code, team, process, leadership, and AI-enabled work. What you notice, what it usually means, what it is NOT, and what to check next. 42
• EP Engineering Playbook Operational playbooks for recurring engineering situations. Steps, actions, outputs, common mistakes - the reference you'd keep open while running one. 40

Two reading modes the design supports equally:

Every detail page shares the same outer chassis so a reader can move across categories without relearning the layout:

• Masthead. Category code + catalog reference number (e.g. FM-05), the entry title, and one or two severity-style pills that map gravity to a grayscale weight ramp.
• MetaRail. A framed strip of ordinal attributes with bar-ladder indicators: severity, frequency, detectability, difficulty, confidence. The same ladders drive the reading-guide tiles on each category landing page.
• At-a-glance. Three to five identity rows: what the entry is, what it is often mistaken for, a calibration cue for when it is not the right read (“not necessarily a problem when” on RF, “do not use when” on EP), and who owns it. Framing, not prose.
• Narrative sections. Category-specific and category-shaped. FM walks the failure arc and closes with notes from practice and recognition boundaries. TD weighs two options in a side-by-side ledger with reversibility and hazard framing. RF moves signal → diagnostic reading → inspection, with false friends rendered as quoted misreads. EP walks a numbered procedure where every step carries its purpose, actions, and outputs.
• Connected patterns. A grid of cross-references into the other three catalogs, resolved through the shared catalog reference codes.

Category identity shows up as accent color on the masthead and on relationship panels. Severity shows up as a grayscale weight ramp. Those two channels stay strictly separate: color is never severity, weight is never category.

AI shows up as a first-class dimension on almost every detail page. Not because AI is inherently special, but because AI is changing how software work actually goes wrong, and a reference that ignores that would be dishonest.

Every entry that has an AI dimension renders the same section: two boxed lists (“AI can help with” / “AI can make worse by”) followed by a blue-serif synthesis callout. Same anatomy on FM, TD, RF, and EP detail pages. On failure modes and tech decisions, entries where AI creates false confidence carry an additional red band above the synthesis. Named explicitly, so the distortion can be read, not smoothed over.

Every entry lists related failure modes, tech decisions, red flags, and playbooks. These are structured references, not free-text footnotes, so a reader can move between adjacent patterns in one click.

Some of those references point to entries that have not been authored yet. When that happens, the site does not hide the reference or fabricate the link. Pending entries render as a dedicated subpanel with a PEND marker next to the slug: honest, visible, and a clear signal of editorial backlog. They do not render as broken links.

If a pending reference keeps showing up next to entries you care about, that's the site telling you which entry is worth authoring next.

• Not a blog.
• Not a discussion forum.
• Not a learning management system.
• Not a “frameworks for engineering” product.
• Not a tool-marketing site dressed up as editorial.

The goal is the opposite of “one more thing to read”. The goal is a catalog you keep open while thinking.

Written and maintained by a practicing software engineer. Patterns in this catalog are drawn from repeated field observation (what recurs across teams, stacks, and time), not from a branded methodology or a formal framework. Entries are deliberately low-ego: named patterns, not personal war stories.

If an entry lands wrong, if a cross-reference feels forced, or if a pattern is named here that you recognise under a different name, corrections are welcome. Reach the editor at hello@thehardparts.dev.

The reference is published under a Creative Commons Attribution-NonCommercial 4.0 International licence (CC BY-NC 4.0). Quote it, adapt it, share it, build on it. Credit the source and keep the use non-commercial.