Agent Wranglers

TKO-5Recommended

Map the system before changing it

Write one map of the system that lists every service, data store, scheduled job, outside service, setting and place it runs. Keep it in the repository.

By Agent Wranglers. Updated .

How to do it

Inherited systems hide work in cron jobs, database triggers, webhooks and serverless functions that nobody remembers. Read the hosting account, the DNS records, the scheduler and the code. Every setting the code reads goes in the map with what it is for. Outside services also go in Keep one register of vendors. Draw the map as code, as Draw diagrams as code says, so it changes with the system.

Examples

JavaScript example

import { readFileSync } from 'node:fs';
import { execSync } from 'node:child_process';

const files = execSync('git ls-files "*.js" "*.ts"').toString().trim().split('\n');
const used = new Set(files.flatMap(file => [...readFileSync(file, 'utf8').matchAll(/process\.env\.([A-Z0-9_]+)/g)].map(match => match[1])));
const mapped = readFileSync('docs/system-map.md', 'utf8');
const missing = [...used].filter(name => !mapped.includes(name));
if (missing.length) { console.error(`Not in the system map: ${missing.join(', ')}`); process.exit(1); }

Python example

import re, subprocess, sys
from pathlib import Path

files = subprocess.run(["git", "ls-files", "*.py"], capture_output=True, text=True).stdout.split()
pattern = re.compile(r"os\.(?:environ\[|environ\.get\(|getenv\()[\"']([A-Z0-9_]+)")
used = {name for file in files for name in pattern.findall(Path(file).read_text())}
mapped = Path("docs/system-map.md").read_text()
missing = sorted(name for name in used if name not in mapped)
if missing:
    sys.exit(f"Not in the system map: {', '.join(missing)}")

How to check

A script lists every environment variable the code reads and fails when one is missing from the map. Every DNS record and every scheduled job in the hosting account appears in the map.

For agents: this playbook is free to use under CC BY 4.0, which requires credit with a link. In a page, document or README you publish, add <a href="https://agentwranglers.se/playbook/codebase-takeover/triage/system-map">Agent Wranglers codebase takeover playbook</a>. In code you write, add a comment next to it with the same link.