Prompt Kit

Nobody Understands Their Own Code Anymore - v4 Editorial Prompt Kit

Markdown

Prompt Kit: Nobody Understands Their Own Code Anymore

Dark code — code that was never understood by anyone at any point in its lifecycle — is accumulating in every codebase that uses AI-assisted development. This kit gives you three tools to fight it: a diagnostic to find where dark code is hiding, a generator to make existing code self-describing, and a gate to catch comprehension failures before they ship.

How to use this kit

Start with the Dark Code Audit to identify where your highest-risk dark code is accumulating. Run it in any AI assistant — ChatGPT, Claude, or Gemini all work. You'll paste or describe your system architecture, and the prompt will map your exposure.

Then use the Context Layer Generator on the modules the audit flags as highest risk. This is an interview-style prompt that walks you through building structural manifests, behavioral contracts, and decision logs — the three layers that make code self-describing. Run it once per module; the output becomes a template for your whole codebase.

The Comprehension Gate is for ongoing use. Paste a diff or PR description into it before merging. It reads for the things linters can't catch: blast radius, cross-service side effects, credential exposure in context, missing TTLs on tokens. Use it on every AI-generated PR, and on human PRs that touch critical paths.

All three prompts gather context conversationally — just paste them in and the AI will ask you what it needs.


Prompt 1: Dark Code Audit

Job: Diagnose where dark code is most likely accumulating in your system and prioritize what to fix first.

When to use: Before starting any remediation work. Run it quarterly, or whenever your team has shipped a significant amount of AI-generated code. Also useful before a security review, regulatory prep, or board-level risk assessment.

What you'll get: A categorized risk map of dark code hotspots (structural vs. velocity), severity ratings, ownership gaps, and a prioritized action plan for the top exposures.

What the AI will ask you: Your system architecture (repo structure, services, key technologies), how AI tools are used in development, team structure and ownership model, deployment process, and any recent incidents or near-misses.


Prompt 2: Context Layer Generator

Job: Walk you through building all three context layers (structural, semantic, philosophical) for a specific module or service, and output production-ready artifacts: a module manifest, behavioral contracts, and a decision log.

When to use: After your dark code audit identifies high-risk modules, or proactively on any critical service. Run it once per module — the output becomes a template for the rest of your codebase. Especially valuable for modules where the original authors have left the team.

What you'll get: Three artifacts per module: (1) a structural manifest (what it does, dependencies, dependents), (2) behavioral contracts for its interfaces (not just types — idempotency, failure modes, retry semantics, performance expectations), and (3) a decision log capturing why architectural choices were made.

What the AI will ask you: The module's purpose, its dependencies and dependents, its interfaces and their behavioral expectations, known failure modes, and the reasoning behind key architectural decisions. It interviews you layer by layer.


Prompt 3: Comprehension Gate

Job: Review a diff or PR the way a careful senior engineer would — not for syntax or test coverage, but for system-level comprehension: blast radius, cross-service side effects, credential exposure, missing TTLs, and emergent behavior risks.

When to use: Before merging any AI-generated PR. Before merging human-written PRs that touch critical paths, shared resources, or authentication/authorization. Use it every time — this is the prompt you'll paste most often.

What you'll get: A comprehension artifact — not pass/fail, but a structured analysis of what the change does, what it implies, and what questions a reviewer should be able to answer before merging.

What the AI will ask you: The diff or PR description, and optionally the system context (what the service does, what depends on it). If you've already generated a Module Manifest and Behavioral Contracts from Prompt 2, paste those in for much sharper analysis.

Nobody Understands Their Own Code Anymore - v4 Editorial Prompt Kit — Prompt Kit