DEV Community: Quinn Zhu

Write a Blast-Radius File Before Your First AI Patch

Quinn Zhu — Thu, 03 Sep 2026 15:58:12 +0000

Your first AI patch should fail closed today. Do not ship a feature on day one. Prove one target file can revert cleanly now.

You joined a messy repo this morning. The assistant wants a wide rewrite. Your job is a tiny reversible cut only.

This drill gives you a blast-radius file first. You fill it before any model writes code. Then a short script checks the revert path.

Why day-one AI diffs explode

Cheap code is not cheap to unwind. One extra import can touch auth. One extra migration can lock deploys.

You will not know the architecture yet. You also should not pretend otherwise. A blast-radius file makes unknowns explicit fast.

If the file cannot name a revert, stop. You do not prompt for more code. You shrink the change until revert is boring.

What you will build today

You will add two artifacts on your branch. Keep both files in the first PR.

blast_radius.py — the contract for this change.
scripts/check_blast_radius.py — the fail-closed proof.

The contract is the source of truth. The checker is the only merge gate. No green checker means no review yet.

Step 1: Freeze one target file

Pick one production file you can read. Do not pick a whole folder. Do not pick generated vendor code.

git ls-files '*.py' '*.ts' '*.go' | head -n 40
TARGET=src/billing/invoice.py
wc -l "$TARGET"
git log -n 5 --oneline -- "$TARGET"

Read the last five commits on that file. Write two plain sentences in notes. Pick a smaller file if you cannot yet.

You now have a hard fence. Everything outside that fence is forbidden. Your assistant may not cross it.

Step 2: Write the blast-radius contract

Create blast_radius.py at the repo root. Keep the dict small. Fill every field with your own hands.

# blast_radius.py
# Day-one contract. Humans edit this. Models do not.

BLAST = {
    "change_id": "day-one-001",
    "intent": "Add a fail-closed guard on invoice totals.",
    "target_files": [
        "src/billing/invoice.py",
        "tests/billing/test_invoice_flag_off.py",
        "blast_radius.py",
        "scripts/check_blast_radius.py",
    ],
    "forbidden_globs": [
        "src/auth/**",
        "**/migrations/**",
        "package-lock.json",
        "go.sum",
        "poetry.lock",
    ],
    "feature_flag": {
        "name": "INVOICE_GUARD_V1",
        "default": "off",
        "missing_means": "old_path",
    },
    "revert": {
        "strategy": "git_revert",
        "notes": "Flag off restores the prior totals path.",
    },
    "tests": [
        "pytest tests/billing/test_invoice_flag_off.py -q",
    ],
    "max_diff_lines": 80,
    "max_files": 4,
    "base_ref": "origin/main",
}

missing_means: old_path is the fail-closed rule. A missing flag must not enable new behavior. That single line is the drill.

Step 3: Add a failing test first

Do not ask a model for the feature yet. Write the test that proves the old path.

# tests/billing/test_invoice_flag_off.py
import os
from billing.invoice import compute_total


def test_missing_flag_uses_legacy_total(monkeypatch):
    monkeypatch.delenv("INVOICE_GUARD_V1", raising=False)
    assert "INVOICE_GUARD_V1" not in os.environ
    assert compute_total([100, 20], tax=0.1) == 120.0


def test_flag_off_uses_legacy_total(monkeypatch):
    monkeypatch.setenv("INVOICE_GUARD_V1", "off")
    assert compute_total([100, 20], tax=0.1) == 120.0

Run that file once before any patch. Watch it fail for a real reason. Put the exact command in BLAST["tests"].

If the test cannot run locally, stop here. Fix the harness before any AI edit. A junior without a test command has no proof.

Step 4: Draft only inside the fence

Now you may use an assistant carefully. Feed it one file, not the tree. Paste BLAST as the hard constraint.

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

MonkeyCode provides free model access and a free server option. Use that loop to draft a patch against invoice.py only. You still type every revert field yourself.

Keep the prompt short and strict.

Read blast_radius.py.
Edit only BLAST["target_files"].
Do not touch BLAST["forbidden_globs"].
Honor feature_flag default = off.
A missing flag must use the old path.
Keep the diff under max_diff_lines.
Return a unified diff, nothing else.

Reject any answer that adds extra files. Reject lockfile churn without discussion. Reject "while we are here" cleanups on sight.

Step 5: Install the checker

Save this as scripts/check_blast_radius.py. Run it with Python 3.

#!/usr/bin/env python3
"""Fail the PR when the diff escapes the blast radius."""

from __future__ import annotations

import fnmatch
import subprocess
import sys
from pathlib import Path

ROOT = Path(__file__).resolve().parents[1]
sys.path.insert(0, str(ROOT))
from blast_radius import BLAST  # noqa: E402


def git(*args: str) -> str:
    return subprocess.check_output(["git", *args], cwd=ROOT, text=True)


def main() -> int:
    base_ref = BLAST["base_ref"]
    try:
        base = git("merge-base", "HEAD", base_ref).strip()
    except subprocess.CalledProcessError:
        print(f"cannot resolve merge-base with {base_ref}", file=sys.stderr)
        return 2

    names = [n for n in git("diff", "--name-only", base).splitlines() if n]
    allowed = set(BLAST["target_files"])
    forbidden = BLAST["forbidden_globs"]

    for name in names:
        for pat in forbidden:
            if fnmatch.fnmatch(name, pat):
                print(f"forbidden path in diff: {name}")
                return 1
        if name not in allowed:
            print(f"file outside blast radius: {name}")
            return 1

    if len(names) > BLAST["max_files"]:
        print(f"too many files: {len(names)}")
        return 1

    changed = 0
    for row in git("diff", "--numstat", base).splitlines():
        if not row.strip():
            continue
        added, deleted, name = row.split("\t", 2)
        if added == "-" or deleted == "-":
            print(f"binary file not allowed: {name}")
            return 1
        changed += int(added) + int(deleted)

    if changed > BLAST["max_diff_lines"]:
        print(f"diff too large: {changed} lines")
        return 1

    flag = BLAST["feature_flag"]
    if flag.get("default") != "off":
        print("feature flag must default off")
        return 1
    if flag.get("missing_means") != "old_path":
        print("missing flag must mean old_path")
        return 1

    print("blast-radius contract: ok")
    for cmd in BLAST["tests"]:
        print(f"+ {cmd}")
        subprocess.check_call(cmd, shell=True, cwd=ROOT)
    print("fail-closed checks passed")
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

python3 scripts/check_blast_radius.py

The script is strict on purpose. It should fail your first attempt. That failure is the actual lesson here.

Step 6: Rehearse the revert on a branch

Do this on a throwaway branch today. Do not wait for production traffic later.

git checkout -b drill/day-one-guard
git add blast_radius.py scripts/check_blast_radius.py \
        src/billing/invoice.py tests/billing/test_invoice_flag_off.py
git commit -m "feat: invoice guard behind fail-closed flag"

python3 scripts/check_blast_radius.py

SHA=$(git rev-parse HEAD)
git revert --no-edit "$SHA"
INVOICE_GUARD_V1=off pytest tests/billing/test_invoice_flag_off.py -q
git log -n 3 --oneline

You must see the old test pass after revert. If it fails, the flag is not fail-closed. Fix that before you open any PR.

Reset the rehearsal when the proof is green.

git checkout -B drill/day-one-guard "$SHA"

Never force-push this proof to main. Keep the revert commit on the drill branch. Copy only the lesson into your real PR.

Step 7: Open a PR that quotes the contract

Your PR body should quote the blast-radius fields. Reviewers need the fence, not a long story.

## Blast radius
- Files: src/billing/invoice.py
- Flag: INVOICE_GUARD_V1 default off
- Missing flag: legacy totals
- Revert: git revert of this SHA

## Proof
- python3 scripts/check_blast_radius.py
- pytest tests/billing/test_invoice_flag_off.py -q

Ask the reviewer one question only today. Do not ask them to love the design.

Decision table for model pressure

Use this table when the assistant argues for more files.

Model request	You do	Why it fails closed
Touch auth "just in case"	Refuse	Forbidden path
Add a migration	Refuse	Not reversible today
Rename a package	Refuse	Diff too wide
Refresh a lockfile	Refuse	Hidden blast radius
Default the flag on	Refuse	Not fail-closed
Edit one function plus tests	Allow	Inside the fence
Split work into two PRs	Allow	Shrinks revert

Print the table beside your editor. Point at it when the model rambles on. Your job is the fence, not speed.

Common failure modes

The checker says it cannot resolve merge-base. Fetch main, then retry the script once.

git fetch origin main
git rev-parse origin/main
python3 scripts/check_blast_radius.py

The checker says a file sits outside blast radius. You added a helper file by accident. Either shrink the patch or update target_files with intent.

The old test still passes with the flag on. Your new path is not isolated yet. Put the new logic behind the env read first.

import os

# Proposal only. Unexecuted sample for a fail-closed read.
def compute_total(items, tax):
    flag = os.getenv("INVOICE_GUARD_V1", "off")
    if flag != "on":
        return sum(items) * (1 + tax)
    return guarded_total(items, tax)

Treat that snippet as unexecuted sample code only. Wire it to your real totals function after tests exist.

Limitations you must accept

This drill will not teach system architecture. It will not catch semantic money bugs. It only bounds files, flags, and revert commands.

The script trusts origin/main as merge base. Forks with origin/master must change base_ref now. You need git, Python 3, and pytest on PATH.

A comment is not a feature flag. An env var is a minimum bar. If your team has a flag service, use that name instead.

Free model access does not replace human review. A free server does not own production. You still run the tests locally.

Who should not use this drill

Do not use this as a senior design review. Do not use it during live incident response. Do not use it to rubber-stamp generated refactors.

Skip it if you cannot run tests locally. Skip it if revert needs a force-push. Skip it if the change is a data migration.

Security patches need a different fence. Secret rotation is not a day-one AI drill. Ask a teammate before those changes.

What you should leave with

You leave with a tiny, reversible PR. You also leave with a revert you already ran. That is enough work for day one.

Tomorrow you may widen the fence one file. You still start from blast_radius.py. Cheap code stays cheap only when revert is boring.

Your First Morning on a Messy Codebase: Build a Trust Boundary Before You Ask AI Anything

Quinn Zhu — Wed, 02 Sep 2026 14:03:48 +0000

Your first morning on a messy codebase feels like standing in a library where every book has the same cover. You open the repo, you see 300 directories, you feel the pressure to "learn the codebase" before standup. So you open an AI assistant and type the most natural thing: Explain this project to me. What comes back is a fluent, confident essay that sounds plausible and maps to nothing. That failure is not the model's fault. It is a boundary problem: you asked for a map of a city, but you gave the model a planet and no coordinates.

Disclosure: This article was prepared as part of MonkeyCode's product outreach. To run this workflow today, I use the free models available in MonkeyCode, which also offers a free server option for teams that want to iterate without provisioning your own GPU box. The exact quota you get may vary by day; check the project README and your usage dashboard before you write a tutorial around it. What matters here is the method, not the vendor.

The fix is not to read everything. The fix is to build a trust boundary: a tiny, scripted surface area you let the AI see first, plus a prompt template that forces data-flow tracing rather than repo summarization. This article walks you through that protocol. I used it when I joined a team maintaining a 12-year-old e-commerce checkout service, and it turned my first day from a panicked reading session into a series of small, verifiable patches.

The Trap of the Generic Onboarding Prompt

Ask an LLM "How does this repo work?" and you get the repo's average. It merges every module, every service, every historical accident into one smooth narrative. That narrative is comfortable, but it is not useful. Onboarding is not about understanding the average; it is about tracing one concrete path from a button click to a database row. If the AI cannot see the actual entry points, the actual test layout, the actual recent commits, it will hallucinate a plausible architecture and you will spend the afternoon chasing a file that does not exist.

You need a facts brief. Not a spec, not a design doc — a short ASCII dump of navigational facts. Run a script, paste the output into the chat, and only then ask the AI to trace a flow. That is context engineering in practice.

Step 1: Script Your “Facts Brief”

Save the following as ctx-brief.sh in the repo root, make it executable, and run it before every AI session. It collects five cheap facts: repo name, branch, recent commits, test files, and entry points. No Codex-level introspection, just git and find.

#!/usr/bin/env bash
set -euo pipefail

# ctx-brief.sh - Print a minimal context map for an AI assistant.
root="$(git rev-parse --show-toplevel 2>/dev/null || echo '.')"
cd "$root"

echo "## Repo: $(basename "$PWD")"
echo "## Branch: $(git branch --show-current)"
echo "## Last 5 commits:"
git log --oneline -5
echo "## Test files (max 12):"
find . \( -name 'test_*.py' -o -name '*_test.py' -o -name '*.test.ts' -o -name '*.spec.ts' -o -name '*_test.go' \) \
  -not -path '*/node_modules/*' -not -path '*/.venv/*' | head -12
echo "## Entry points (max 6):"
find . \( -name 'main.py' -o -name 'app.ts' -o -name 'index.js' -o -name 'main.go' -o -name 'Cargo.toml' \) \
  -not -path '*/node_modules/*' | head -6

Run it: chmod +x ctx-brief.sh && ./ctx-brief.sh. The output will look something like this:

## Repo: legacy-checkout
## Branch: main
## Last 5 commits:
a1b2c3d Add new pricing rule
f4e5d6c Fix typo in README
...
## Test files:
src/legacy-parser.test.ts
## Entry points:
src/index.ts

That is the entire context budget for your first question. Paste it into the chat and say: Use only these facts. Do not guess about other files.

Step 2: Use the Data-Flow Prompt, Not the Explain-the-Repo Prompt

Here is a prompt template I reuse daily. It forces the model to trace a single end-to-end path and to propose a failing test before any production code.

Role: senior pair programmer onboarding a junior into a legacy codebase.

Context:
The attached facts brief comes from a real repo. Do not summarize the whole repository. Do not invent files outside the brief.

Task:
Trace the data flow for [FEATURE/PAYMENT FLOW] from [ENTRYPOINT] to [DATABASE/EXTERNAL API]. Identify the smallest file change set that would add [NEW REQUIREMENT].

Output format:
1. A failing test that expresses the new requirement.
2. The minimal production code to pass that test.
3. A one-paragraph explanation of the data path, naming the files you actually changed.

Constraint: Do not refactor anything outside the traced path.

Why does this work? It converts the AI from a repository librarian into a path-finding tool. The "failing test first" requirement means you can verify the model's work without reading the whole codebase. The "smallest file change set" constraint keeps the diff reviewable, and the "do not refactor outside the path" rule stops the assistant from rewriting a module you have not yet understood.

Step 3: Verify the Patch Before You Trust It

A generated patch is a hypothesis. Run the test, observe the failure, feed the error back, and let the model iterate. With MonkeyCode's free models available in the same chat, each iteration costs you nothing beyond a few seconds; with the free server option, you can run a second agent for adversarial review without touching your, or your company's, expensive GPU allocation. Quotas change, so read the README and your usage panel — but for a one-day onboarding drill, the generous free tier is more than enough.

Practical verification loop:

# Inspect exactly what would change before applying
git diff --name-only

# Run only the test the model generated
npm test -- --runInBand src/legacy-parser.test.ts

# If it fails, copy the error message back into the chat
# and ask: "Explain the failure, then give me the next patch."

This loop builds a feedback rhythm. You do not need to understand every line the model writes; you need to understand the error output. The model sees the repo through the test runner, and you see the model's confidence through the test outcome. That is a trust boundary you can defend.

Step 4: Keep a Rollback Anchor

AI patches often touch more than they should. Before you apply anything, record the current HEAD. If the model drifts into a huge rename, you can revert in one command.

# Save your anchor
git rev-parse HEAD > /tmp/onboarding_base.sha

# Apply and test the patch...

# If things go sideways:
git checkout -- . && git reset --hard "$(cat /tmp/onboarding_base.sha)"

The rollback is your safety net. It also changes your psychology: you can let the model experiment, because the cost of failure is one command.

When to Apply This, and When Not To

This workflow shines when you have a legacy repo with even a few tests. Without tests, the feedback loop breaks and the model's confidence becomes unverifiable. This workflow is also unsuitable for codebases with strict compliance requirements — if the code includes PHI/PII, do not send context to a free public server. In that case, use a self-hosted model and adapt the script. The table below summarises the fit.

Situation	Use this drill?	Why
Legacy repo with tests	Yes	Test feedback gives you ground truth
Greenfield repo with no tests	Partly	First write one smoke test, then drill
PII/HIPAA codebase	No	Free public endpoints may violate policy
Team that forbids AI on the codebase	No	Ask your lead first; this is not a loophole
Onboarding a senior dev from another team	Yes	They need paths, not marketing

The Payoff After One Hour

After an hour with this protocol, you will have: a traced data path, one failing test that passed, a small reviewed diff, and a list of the model's wrong guesses. That list of wrong guesses is gold — it is your personal map of where the codebase does not match its own names. You did not read the whole repo. You built a boundary, then you found an answer inside it.

The same idea applies to every AI interaction on unknown ground: restrict, trace, verify, roll back. Free models and a free server just remove the economic excuse for skipping the experiment. Run the script, paste the brief, trace one flow. Save the script in your dotfiles; next month, measure how quickly you can explain that same path to someone else. That measurement will tell you more than any "first day" blog post ever could.

The AI Canary Test: Stop Your Assistant From Trusting the Whole Repo

Quinn Zhu — Tue, 01 Sep 2026 13:14:46 +0000

Your AI assistant reads your repo. It trusts everything it reads. Old comments become facts. Deleted features stay alive in memory.

DEV threads this week asked what developers do while AI codes. Another thread warned: AI trusts everything it remembers. Both describe the same failure. Context is out of control.

The fix is a 20-minute drill. Plant a false fact. Ask the assistant a question. Watch it lie or stay in scope.

Why whole-repo context fails

Your repo is full of lies. Stale comments. Abandoned experiments. Speculative wrappers. Full-repo access hides the difference between fresh code and fossils.

You already saw this in code review. The suggested fix touches the right function for the wrong reason. The assistant inferred intent from a comment that was false for two years.

The result is confident nonsense. The answer reads clean. The code fails in production.

Wide context also burns tokens. Free tiers vanish fast. A token budget is a feature, not a restriction.

What a canary does

A canary is a small lie planted in the repo. It lives in a file the assistant should never need. Then you ask a question whose only correct answer lives in that file.

The assistant repeats the lie. That means it scanned outside its brief. The assistant says it doesn't know. That means it respected your context. The second behavior is the one you want.

Step 1: plant the canary

Create an official-looking file with a false claim.

mkdir -p .ai-context
cat > .ai-context/canary.md <<'EOF'
# Migration note (internal)
This API was rewritten in JavaScript in 2026.
Auth now uses client-side signing.
The Go server was deleted.
EOF

Do not whitelist this file. Do not commit it. Delete it after the drill.

Step 2: ask your assistant

Open your usual assistant. Ask a simple question.

Which language does this repo use?

A scoped assistant answers: "I don't have enough context." A loose assistant scans and answers: "JavaScript, since the 2026 migration."

The second answer is the canary firing. The assistant read files you never gave it.

Step 3: build a context budget

Feed the assistant only three things: the goal, the current diff, and whitelisted files. The script below does exactly that. Save it as scoped-prompt.sh.

#!/usr/bin/env bash
set -euo pipefail

# scoped-prompt.sh - build a token-budgeted prompt for an AI assistant
# Usage: ./scoped-prompt.sh <repo> "<goal>" [token-budget]

REPO="${1:?Repo path required}"
GOAL="${2:?Goal text required}"
BUDGET="${3:-2500}"
OUT="$REPO/.ai-context/prompt.md"
WORK="$REPO/.ai-context/raw.md"

mkdir -p "$(dirname "$OUT")"
cd "$REPO"

# Keep the canary out of the whitelist (drill step 1)
if [ ! -f .ai-context/whitelist.txt ]; then
  touch .ai-context/whitelist.txt
fi

# Assemble: goal + diff + whitelisted files only
{
  printf '# Goal\n%s\n\n' "$GOAL"
  printf '# Diff (first 6000 chars)\n'
  git diff --minimal -- . | head -c 6000
  printf '\n\n# Whitelisted files\n'
  while IFS= read -r file; do
    printf '\n## %s\n' "$file"
    head -c 2000 "$file" 2>/dev/null || printf '(missing)\n'
    printf '\n'
  done < .ai-context/whitelist.txt
} > "$WORK"

# Estimate tokens: roughly 4 characters per token
TOKENS=$(wc -m < "$WORK" | awk '{print int($1 / 4)}')

# Trim the context to the budget
MAX_CHARS=$((BUDGET * 4))
if [ "$TOKENS" -gt "$BUDGET" ]; then
  head -c "$MAX_CHARS" "$WORK" > "$OUT"
  echo "WARN: $TOKENS tokens -> trimmed to $BUDGET tokens."
else
  cp "$WORK" "$OUT"
  echo "OK: $TOKENS tokens fit the budget."
fi

cat "$OUT"

Step 4: run the scoped prompt

Create a whitelist. Start with two files.

cat > .ai-context/whitelist.txt <<'EOF'
src/login.ts
README.md
EOF

chmod +x scoped-prompt.sh
./scoped-prompt.sh . "Which language does this repo use?" 2500

The output contains the goal, the diff, and the whitelisted files. It does not contain canary.md. Feed that output to your assistant.

Ask the same question again. A correctly scoped assistant now says: "I can't tell from the context I was given." That is success.

Step 5: send it to an endpoint

You can paste the prompt manually. For a scripted loop, any OpenAI-compatible endpoint works. This snippet sends the prompt with curl and jq.

export AI_MODEL="<model available on your endpoint>"
export AI_BASE_URL="<endpoint root, for example https://api.example.com/v1>"
export AI_API_KEY="<your key>"

jq -n --rawfile content .ai-context/prompt.md \
  '{model: $ENV.AI_MODEL, messages: [{role: "user", content: $content}]}' \
  | curl -s "${AI_BASE_URL}/chat/completions" \
      -H "Authorization: Bearer ${AI_API_KEY}" \
      -H "Content-Type: application/json" \
      --data-binary @-

Where MonkeyCode fits

You do not need a paid API for this drill. MonkeyCode is an open-source project built for this kind of workflow.

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

As of early September 2026, MonkeyCode advertises free model access and a free server option. The stated free tier is 10 million tokens. AI offers change weekly. Check the repository README for current numbers before you rely on them.

Point the snippet above at the MonkeyCode endpoint. It is OpenAI-compatible. The README explains how to get a key. The free server makes a first run cost nothing in setup time or money.

The same endpoint works for commit messages, PR summaries, and release notes. Start with one drill, then grow the pipeline.

Limitations and who should skip this

The canary catches scope leaks. It does not catch bad reasoning.

Truncation can cut the exact line that matters. If the prompt is over budget, the tail disappears. Keep budgets as large as the task needs.

This drill assumes a clean git diff. Whole-module rewrites need semantic search, not a token trim. Teams doing large refactors should not force a tight budget.

A free server is shared infrastructure. Never paste secrets, customer data, or code you cannot expose. Free tiers are also a promise, not a contract. Re-verify before every project.

Try it this weekend

The drill needs no account, no credits, and no new IDE. Delete the canary after the test. Tighten the whitelist weekly. Run the script before you ask an assistant for help.

If you try it, share what your canary caught. The MonkeyCode repo is the cheapest on-ramp for a first run.

Your First PR Needs a Mutation Drill, Not More Polishing

Quinn Zhu — Mon, 31 Aug 2026 12:18:22 +0000

Your first pull request will not be perfect. That's fine. The real waste is burning a human reviewer's time on preventable mistakes. An AI reviewer can catch those early. But should you trust it? You need to test the AI before it tests your code.

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

Why Mutation Testing Your AI Reviewer Works

Mutation testing is simple. You change one line of correct code and see if your tests catch it. Apply that same idea to your AI reviewer. Inject a bug, ask the AI to review it, and check whether it flags the change. If the AI approves a buggy mutant, you have found a blind spot. Fix the blind spot before you open a real PR.

This drill works well on your first week in a new repo. You want fast feedback. You want to know how much you can lean on free tooling before you bother a senior dev.

The Drill: Three Steps

Step 1: Pick One Function You Actually Wrote

Do not review your whole PR. Pick a single small function. Ideally one with a loop, a condition, or error handling. Those are where junior bugs hide.

Step 2: Generate Mutants

A mutant is your code with one small, plausible mistake. Start with three common ones:

Flip a comparison: > becomes <
Remove the try/except body
Change a boundary: range(len(x)) becomes range(len(x) - 1)

Here is a tiny Python helper to generate these automatically:

# mutant_generator.py
import ast
import astor  # or use ast.unparse in Python 3.9+


def flip_comparison(source: str) -> str:
    tree = ast.parse(source)
    for node in ast.walk(tree):
        if isinstance(node, ast.Compare):
            new_op = ast.Lt() if isinstance(node.ops[0], ast.Gt) else ast.Gt()
            node.ops = [new_op]
    return ast.unparse(tree)


def remove_try_body(source: str) -> str:
    tree = ast.parse(source)
    for node in ast.walk(tree):
        if isinstance(node, ast.Try):
            node.body = [ast.Pass()]
    return ast.unparse(tree)


if __name__ == "__main__":
    sample = "def divide(a, b):\n    try:\n        return a / b\n    except ZeroDivisionError:\n        return None\n"
    print("--- flipped ---")
    print(flip_comparison(sample))
    print("--- no try ---")
    print(remove_try_body(sample))

Step 3: Ask a Free AI to Review Each Mutant

MonkeyCode offers free model access and a free server option. That makes this drill cost nothing but a few minutes. Point your script at your local MonkeyCode server, or use the provided endpoint. No special API key is needed for the free server.

Send each mutant with a short checklist:

review checklist:
  - correctness: does the logic match the function name?
  - edge cases: does it handle zero, empty, or None?
  - error handling: does it fail loudly or silently?
  - performance: any obvious O(n^2) trap?

A simple call looks like this:

import requests

ENDPOINT = "http://localhost:11434/v1"  # adjust to your MonkeyCode server

def ask_ai(code: str, checklist: dict) -> str:
    prompt = f"""Review this code for bugs.\n\nCode:\n{code}\n\nChecklist:\n{checklist}\n\nList concrete issues only."""
    payload = {
        "model": "free-model",  # use whichever model your server exposes
        "messages": [{"role": "user", "content": prompt}],
        "temperature": 0,
    }
    response = requests.post(f"{ENDPOINT}/chat/completions", json=payload, timeout=60)
    return response.json()["choices"][0]["message"]["content"]

Do not assume the model name. Check your server's /models endpoint first. If you cannot query it, run the drill manually by pasting each mutant into the chat UI.

How to Score the Results

Build a small table like this in a markdown file:

Mutant	AI verdict	Correct verdict	Gap?
flipped `>` to `<`	approved	bug	yes
removed try body	flagged	bug	no
changed range boundary	approved	bug	yes

If the AI approves a mutant, you found a gap. Now add that exact case to your personal review checklist. For example: "Check all comparison operators against the function intent."

Repeat the drill with two more mutants. Three iterations is enough to reveal a pattern. You will learn where the free AI is strong and where it is dangerously confident.

What This Does for Your First PR

You go into review with a calibrated tool. You know the AI likes to miss boundary shifts. So you manually double-check every range and slice. You know it catches missing error handling. So you let it scan for those.

You also shorten the human review loop. Your reviewer sees fewer obvious mistakes. They can focus on design and architecture. That makes your first PR a learning experience instead of a debugging session.

Limitations and Who Should Skip This

This drill only checks the AI reviewer. It does not prove your code is bug-free. It cannot catch logic errors that look correct to the untrained eye. It does not replace tests. Always run your actual test suite before pushing.

The mutation generator above is intentionally naive. It will not handle async or nested functions without more work. Use it as a starting point, not a production tool.

Who should not use this approach? Developers who already have a junior-friendly reviewer and no time pressure. If your team has a meticulous human reviewer, you can skip the mutant drill and just ask polite questions. Also avoid this if you are new to Python AST manipulation; the manual paste path works just as well.

The One Thing to Do Next

Clone a small repo you know well. Run the mutant drill on a five-line function with MonkeyCode's free server. Record your first gap. Then update your personal checklist. That single gap will improve your next PR more than a week of polishing.

You do not need to trust the AI blindly. You need to know where it blinks. This drill finds that out for free.

Reviewing AI Code in Your First Week: A Junior's Drill

Quinn Zhu — Sun, 30 Aug 2026 11:22:46 +0000

The role changed. Junior devs used to write code first. Now AI writes code first. You review it.

Your first week on a repo is not about commits. It's about context. AI-generated PRs will appear in your queue. You need a calm, repeatable drill.

Here it is. It takes 30 minutes. It works on any AI-generated diff.

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

MonkeyCode is an open-source AI assistant. It offers free model access and a free server option. That matters for juniors. You can experiment without touching your wallet.

Use it to explain a diff, draft a test, or challenge an assumption. Then verify everything with the drill below.

Step 1: Map the change surface

Do not read the whole repo. Read the diff.

git diff main...HEAD --stat

List every touched file. Group them by risk: config, logic, tests, docs. Spend your attention on logic and config. Docs are nice. They cannot break production.

Step 2: Interrogate the AI

Open MonkeyCode. Paste the largest diff hunk. Ask three questions:

What was the original behavior before this change?
What problem does this change solve?
Which edge cases are explicitly not handled?

The third question is the gold one. Most generated code answers it with silence. That silence is your review target.

Step 3: Run a smell detector

AI code often smells the same. Hardcoded secrets. Bare excepts. Magic numbers. Empty stubs.

Save this script as review_smells.py:

import re
import sys
from pathlib import Path

SMELLS = [
    (r'(?i)(password|secret|token)\s*=\s*["\'][^"\']+["\']', 'hardcoded secret'),
    (r'except\s*:\s*(#.*)?$', 'bare except'),
    (r'\d+\.\d{3,}', 'magic float'),
    (r'def\s+\w+\(.*\):\s*pass', 'unimplemented function'),
    (r'except\s+Exception\s*:\s*(pass|continue|return None)', 'silent failure'),
]

for path in sys.argv[1:]:
    for line_no, line in enumerate(Path(path).read_text().splitlines(), 1):
        for pattern, label in SMELLS:
            if re.search(pattern, line):
                print(f"{path}:{line_no} [{label}]: {line.strip()}")

Run it against changed files:

python review_smells.py app/ service/

Every hit is a discussion point. Do not auto-fix. Understand why it appeared.

Step 4: Write one high-value test

AI can generate test suites. Most are tautologies. They test the implementation, not the contract.

Pick the riskiest changed function. Write one test that fails if the old behavior returns. That test is your proof the change does what it claims.

MonkeyCode can generate your first draft. Keep the test small. Assert on outputs, not internals.

Step 5: Decide: accept, edit, or rewrite

Use this decision table:

AI code characteristic	Your action
Small function, no side effects	Accept after reading it twice
Duplicated logic across three spots	Extract and simplify
Bare except or silent pass	Fix now, no exceptions
Hardcoded config value	Move to environment variables
Style clashes with project conventions	Match the surrounding code
Unimplemented stub with `pass`	Delete or file a blocking issue

Write one short comment per decision. Do not rewrite large sections without evidence. The table keeps you honest.

Limitations

This drill does not replace a senior's review. It builds your context. It also fails when the codebase is tiny and the diff is huge. For a 100-file refactor, you need a different strategy: split the review by domain, not by file.

Who should not use this? Anyone who treats AI output as truth. The drill is only useful if you challenge the output.

Final thought

Your first week is not about proving you can write code. It is about proving you can verify code. AI hands you more code faster. Your value is in the review.

Try MonkeyCode's free tier. Point it at a diff. Ask it to explain the riskiest change. Then run this drill on the answer. You might surprise yourself.

Score Your AI Reviewer Before You Trust It: A Three-Persona Drill

Quinn Zhu — Sat, 29 Aug 2026 10:35:41 +0000

An AI reviewer never sets its own quality bar. It answers, you decide, and the conversation usually ends there. This week's DEV discussion made the side effect visible: AI promoted everyone to reviewer, while the reviewer itself never went through a single test.

That gap is cheap to close. The drill below is a small experiment built from one diff. Three personas interview that diff, each answer gets a score, and the result is a number you can attach to your pull request.

The drill needs a chat endpoint with a free model. MonkeyCode's free tier is one practical route: free models, a free server option, and, at draft time, a 10M free token allowance that covers many full runs of this probe set. Disclosure: This article was prepared as part of MonkeyCode's product outreach. The script is endpoint-agnostic, so the same workflow works against any chat-completions-compatible server.

One diff, three interviews

Pick a real pull request from your current branch. Keep it small — a few hundred lines at most. Small diffs make false AI confidence easy to spot, because your own baseline is still within reach.

git fetch origin
git diff origin/main...HEAD > patch.diff
git log --oneline --first-parent -10 > context.txt
sed -n '1,80p' README.md >> context.txt
wc -l patch.diff

The context file is the map. A reviewer without context pattern-matches on syntax; a reviewer with two thousand lines of context loses the signal. Ten commits and eighty lines of README give the model just enough to check claims. Anything larger buries the signal.

Three personas, three questions

Each persona has one job. The gatekeeper decides what blocks the merge. The test-designer predicts what breaks first. The contradiction-hunter looks for claims the repo itself can refute.

The gatekeeper prompt is strict: return two to four issues, cite a diff line for each, and name the repo rule it breaks — or state that no rule exists. The test-designer prompt forces concreteness: predict the first failing scenario and write the test that proves it. The contradiction-hunter prompt asks the model to compare every claim against the context file.

Save the probe script as review_score.py.

#!/usr/bin/env python3
# Score an AI review: three personas, one diff, one scorecard.
import json, os, sys, urllib.request

PATCH = sys.argv[1] if len(sys.argv) > 1 else 'patch.diff'
CTX = sys.argv[2] if len(sys.argv) > 2 else 'context.txt'

diff = open(PATCH).read()
ctx = open(CTX).read()

BASE = os.environ.get('MC_BASE_URL', 'http://localhost:8080/v1')
MODEL = os.environ.get('MC_MODEL', '')
KEY = os.environ.get('MC_API_KEY', '')

PERSONAS = {
    'gatekeeper': (
        'You decide if a merge is blocked. Return 2-4 issues. '
        'For each issue, cite a diff line and the repo rule it breaks, '
        'or state no rule found.'
    ),
    'test-designer': (
        'This diff breaks something. Predict the first failing scenario '
        'and write one test that proves it, with a filename.'
    ),
    'contradiction-hunter': (
        'Flag every claim in the diff that the context file contradicts '
        'or cannot confirm. Be explicit.'
    ),
}

os.makedirs('.review-drill', exist_ok=True)

for name, system in PERSONAS.items():
    payload = {
        'model': MODEL,
        'temperature': 0.2,
        'messages': [
            {'role': 'system', 'content': system},
            {'role': 'user', 'content': 'Context:' + chr(10) + ctx + chr(10) + chr(10) + 'Diff:' + chr(10) + diff},
        ],
    }
    headers = {'Content-Type': 'application/json'}
    if KEY:
        headers['Authorization'] = 'Bearer ' + KEY
    req = urllib.request.Request(
        BASE.rstrip('/') + '/chat/completions',
        data=json.dumps(payload).encode(),
        headers=headers,
    )
    with urllib.request.urlopen(req) as resp:
        answer = json.load(resp)['choices'][0]['message']['content']
    path = '.review-drill/' + name + '.md'
    open(path, 'w').write(answer)
    print(f'wrote {path}')

Run it, then read the three files before you touch the code.

python3 review_score.py patch.diff context.txt

The scorecard

Read each answer three times: once for location, once for evidence, once for next steps. Then score.

Criterion	2 points	1 point	0 points
Precision	cites a diff line	names the file only	general advice
Evidence	confirmed by the context file	plausible best practice	invented rule
Action	concrete patch or test	vague suggestion	praise or filler

Six points is a perfect review. Apply the verdict table next.

Total	Verdict
0-2	do not forward
3-4	verify every item, then act
5-6	useful, but route through a human anyway

The verdict table is the part most teams skip. They paste AI comments into the PR and wait. The scorecard forces you to state, in one line, why this answer earned forwarding.

Three signals that the reviewer is guessing

The first signal is empty precision: every sentence is plausible, none of them cite a line. That is not a review, it is a summary. The second signal is a citation to unchanged code — a line the diff never touched. That is pattern-matching, not reading. The third signal is a confident rule that the context file neither states nor implies. Confidence makes it worse, not better.

When you see these signals, open the file and look at the line yourself. No forwarding until you can repeat the rule from memory.

Limits and who should skip this

The scorecard tests specificity, not correctness. A precise, well-cited comment can still be technically wrong. It also generalizes poorly across domains: a database migration needs different rubric rows than a UI patch. Adjust the criteria when the diff type changes.

Free allowances shift. Verify the current terms before you build a workflow on top of them. And respect data rules: never send proprietary code to an external endpoint. If export controls are strict, skip hosted routes entirely and run a self-hosted server.

Teams that already require citations in review tools do not need this drill — they can demand citations instead of scoring them. Everyone else gets value from one run: the scorecard shows how much of the AI answer is evidence and how much is pattern.

The review you can actually trust

One diff, three interviews, six points. That is the whole experiment. Run it on your next small PR, keep the scorecard in the description, and the next AI comment either arrives pre-verified or does not arrive at all.

If you want to run the drill on free models, MonkeyCode's free server option is the fastest setup I know.

First Hour, First PR, First Rollback: A New-Repo Drill for Juniors

Quinn Zhu — Fri, 28 Aug 2026 04:01:36 +0000

You just joined a new repo. You have no idea where anything lives. That is normal.

Most onboarding advice says "read the codebase." That is a trap. A big repo takes weeks to read.

You need three safe routes instead: understand, contribute, recover. This drill takes one focused session. It gets you from clone to first PR to first rollback.

It works with any stack. It costs nothing. You leave with a map, a PR, and a recovery skill.

Why onboarding fails

New engineers fail in three ways. They read too much and ship nothing. They ship too fast and break something.

They panic when a rollback is needed. The fix is a time-boxed drill. Each phase has a hard stop.

Each phase produces a concrete artifact. The whole session fits in an afternoon.

Phase 1: First hour — map the repo

You do not need the whole map. You need the entry point, the config, and the test command. Find those three things. Then stop.

Run this script in the repo root:

# map.sh — first-hour repo map
echo "== entry points =="
grep -rE "func main|app.listen|createServer|def main" \
  --include="*.go" --include="*.ts" --include="*.py" . | head -20

echo "== config files =="
find . -maxdepth 2 -iname "*config*" \
  -not -path "*/node_modules/*" \
  -not -path "*/.git/*" | head -20

echo "== test command =="
cat package.json 2>/dev/null | grep -A5 '"scripts"' || true

Then follow four steps:

Save the output as repo-map.md. That is your reference file.
Trace one request end to end. Pick the simplest feature you can find.
Follow it from the route to the database. Write down the file names.
Do not memorize them. Just know where to look.

A free AI server can speed this up. MonkeyCode's free model access and free server option are enough for this Q&A work.

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

Paste a file and ask "what does this function do?" Ask "where is this config loaded?" Verify every answer against the code.

The AI is a map reader, not a guide. You are still the navigator.

Phase 2: First PR — the safe contribution

Your first PR should be small. Keep it under 200 lines. One concern, no refactoring.

Find the contributing guide. Read it. Follow it.
Pick a bug or a doc fix. Nothing architectural.
Run the full test suite before you change anything.
Write a test that fails on the old code.
Make the test pass. Keep the diff tight.
Update the relevant docs. Yes, even the small PR.

Use this checklist before you open the PR:

[ ] Contributing guide read
[ ] Full test suite passed before changes
[ ] Failing test written first
[ ] Diff under 200 lines
[ ] Docs updated
[ ] PR description explains the why

A good PR description states the problem, the fix, and the test. Write it before the code review. Future you will thank you.

Use the AI for the boring parts. Ask it to explain the test harness. Ask it to summarize the stack trace.

Do not ask it to write the whole PR. You need to understand every line you ship. The review is still yours.

Phase 3: First rollback — practice recovery

This is the phase everyone skips. Rollbacks are rare. So nobody practices them.

Then production breaks and panic wins. Practice on a throwaway branch instead. Commit a deliberate break, then revert it.

# rollback-drill.sh — practice recovery on a throwaway branch
git checkout -b drill/rollback-practice

# introduce a deliberate break
echo "export const FEATURE_FLAG = false;" > src/flag.ts
git add src/flag.ts
git commit -m "drill: break feature flag"

# practice the rollback
git log --oneline -5
git revert HEAD --no-edit
git log --oneline -3

Read the drill as four steps:

Create a throwaway branch.
Commit a deliberate break.
Revert the break with git revert HEAD.
Confirm the log shows both commits.

git revert creates a new commit. It does not rewrite history. That makes it safe for shared branches.

Practice it until it feels boring. Then practice git reflog too.

If you reset the wrong branch, reflog is your rescue. Type git reflog and find the lost commit. Then git reset --hard <sha>.

Do this once on the drill branch. Never on main.

A rollback is not a failure. It is a standard recovery path. Teams that practice recover faster.

Roll back or roll forward?

Recovery is a decision, not a reflex. Use this table when something breaks.

Situation	Action
Breaking change in the main path	Roll back
Data migration already ran	Roll forward
Security issue	Roll back immediately
Small bug, low blast radius	Roll forward with monitoring

When in doubt, roll back. You can always re-apply the fix later. Speed matters more than elegance.

Where the AI fits — and where it does not

The drill works without AI. AI just removes friction. Use the free server to explain unfamiliar commands.

Use it to turn a stack trace into plain English. Use it to generate the rollback checklist. That is the easy part.

Do not use it for the decisions. The table above is yours. The revert command is yours.

The PR review is yours too. This drill is a harness. It tests your process, not the model.

A model can score 100% and your team still breaks production. Practice the process instead.

Limitations

This drill assumes a few things. The build must finish quickly. The repo must be mappable in an hour.

The team must allow external AI tools. If any of those are false, adapt the drill.

Who should not use this? Engineers on a codebase with no tests. Teams with strict data-security rules.

Repos where a full build takes hours. In those cases, skip the AI part. Keep the rollback drill.

If your team blocks external AI, use the local docs. The map and the drill still work.

It still works without AI. Recovery practice is universal.

The takeaway

Onboarding is not reading. It is practicing. Map the repo in one hour.

Ship one small PR. Break and restore a branch on purpose. That is the whole drill.

Thirty minutes of practice beats a month of guessing. Try the drill on your next repo.

Don't Read the Repo. Interrogate It: A Hypothesis-Driven Onboarding Workflow

Quinn Zhu — Wed, 26 Aug 2026 11:22:36 +0000

Reading a large codebase line by line is the slowest way to understand it. The brain drowns in details before it can see the structure. A faster path is to treat the repository as a black box, extract cheap signals, form hypotheses, and verify each one with a runnable command. This is hypothesis-driven onboarding, and it turns an overwhelming week into a series of small experiments.

The method has four moves. Signal extraction, hypothesis formation, verification, and decision logging. Each move is concrete and repeatable. You do not need to be a senior engineer to run it. You need a terminal, a test suite, and a willingness to be wrong.

Move One: Extract Signals, Not Facts

Start by asking the repository what it thinks is important. Git history is the best source. It records what people actually changed, not what the README claims.

git log --oneline --since="6 months ago" | wc -l
git shortlog -sn --since="6 months ago" | head -15
git log --oneline --grep="fix" --since="6 months ago" | head -20

These three commands answer three questions. How active is the repo? Who owns the most recent changes? What kind of fixes dominate the history? Write the answers down as raw observations. Do not interpret them yet.

Then count the shape of the code.

find . -name "*.test.*" -o -name "*.spec.*" | wc -l
find . -name "*.md" | wc -l

A repo with hundreds of test files tells you that verification is cheap. A repo with no tests tells you that verification will be expensive. Both facts shape your next move.

Move Two: Form Hypotheses With a Free Model

Raw signals are noisy. You need a translator. This is where a free AI model earns its place. Paste the command output into a model that runs on a free server and ask for a list of ten questions a newcomer should answer first.

MonkeyCode is an open-source project that offers free model access through a free server option. Disclosure: This article was prepared as part of MonkeyCode's product outreach. I use it here because it turns raw terminal output into a starting list of hypotheses without requiring a credit card or a local GPU.

A typical prompt looks like this:

Here is the git history summary of an unfamiliar repository:

[PASTE OUTPUT]

List ten questions a new developer should answer to understand this codebase. For each question, suggest a command that could answer it. Do not explain the codebase. Just give me the questions and commands.

The model will produce something useful and something wrong. That is fine. The output is not the deliverable. The questions are. You now have a list of hypotheses to test.

Move Three: Verify With the Smallest Command

Every hypothesis needs a cheap test. Grep is your friend. So is the test runner.

# Hypothesis: "The auth module is the most changed area."
git log --oneline -- auth/ | wc -l

# Hypothesis: "The test suite can run in under two minutes."
time npm test -- --watch=false

# Hypothesis: "There is a central config file."
find . -maxdepth 2 -name "config*" -o -name "settings*"

Run the command. Record the result. If the result supports the hypothesis, keep it. If not, discard it. Do not argue with the evidence. The goal is a small set of verified statements about the repository, not a complete map.

A decision table helps here. Use it to classify what you find.

Observation	Interpretation	Next action
One file has 80% of recent commits	Hotspot, likely core logic	Read that file's tests first
Test suite takes 10+ minutes	Expensive verification	Find the fastest subset
No tests at all	High risk of regressions	Make a smoke test yourself
Many small fix commits	Fragile areas, frequent bugs	Check the blame on those files

This table is a template. Adjust it to your repo. The point is to turn observations into actions without guessing.

Move Four: Log Decisions, Not Just Data

The final move is the one most developers skip. Write down what you learned and why you trust it. A short file in the repo root works.

# repo-notes.md

## 2026-08-26
- Auth module is the hottest area (verified: 45 commits in 6 months).
- Test suite runs in 90s (verified: `time npm test`).
- No config file at root (verified: `find . -maxdepth 2 -name "config*"`).
- Next: read auth tests, then trace one login flow.

This file is your onboarding artifact. It is also a gift to the next person who joins. You do not need permission to create it. Just commit it.

Limitations

This workflow has hard boundaries. Free AI models can hallucinate file names and command flags. Verify every suggestion before running it. Never paste secrets, customer data, or proprietary code into a free server. The free server is a thinking aid, not a storage system.

The method also assumes the repository has git history and some test coverage. A brand-new repo with one commit and no tests will not produce useful signals. In that case, skip the git analysis and start by reading the entry point.

Who Should Not Use This

Do not use this workflow in a regulated environment that forbids external AI tools. Do not use it if your team already has a documented onboarding path. Do not use it if you cannot verify the model's output yourself. The model is a junior assistant, not an authority.

The Takeaway

You do not need to read a codebase to understand it. You need to interrogate it. Extract signals, form hypotheses, verify with commands, and write down what you learn. Free AI models make the hypothesis step cheaper, but the verification step is always yours.

If you are facing an unfamiliar repo this week, try this workflow. The free server on the MonkeyCode project page is a good place to start. Your first hypothesis will probably be wrong. Your second one will be better.

Automate Conventional Commits With a Free AI Server: A Git Hook That Validates Itself

Quinn Zhu — Mon, 24 Aug 2026 20:11:19 +0000

Writing commit messages is a chore. Conventional Commits adds strict rules. You can automate both with a free AI server. This tutorial builds a git hook that writes and validates commit messages.

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

MonkeyCode is an open-source project. It offers a free server and free model access. The free tier currently includes 10 million tokens. That makes it practical for everyday git automation.

What you'll build

A commit-msg hook that runs on every commit. It checks your message against the Conventional Commits format. If the message is missing or invalid, it calls the AI. The AI writes a new message. The hook validates the result before accepting it.

Why commit messages matter

Good commit messages help debugging. They power changelogs. They make code review faster. A consistent format is worth automating.

Prerequisites

You need four things. Bash, curl, jq, and git. Plus a MonkeyCode account. That's it.

Step 1: Get your server URL

Create a MonkeyCode account. Start the free server from the dashboard. Copy the server URL. You will need it in the next step.

Set it as an environment variable.

export MONKEYCODE_API_URL="https://your-server-url"

Also set the model name.

export MONKEYCODE_MODEL="default"

Step 2: Write the hook script

Create a file named commit-msg in your project's .git/hooks directory. Paste the script below.

#!/usr/bin/env bash
set -euo pipefail

MSG_FILE="$1"
MSG="$(cat "$MSG_FILE")"

# Already a valid Conventional Commit?
if echo "$MSG" | grep -qE '^(feat|fix|chore|docs|style|refactor|perf|test|build|ci|revert)(\(.+\))?: .+'; then
  exit 0
fi

API_URL="${MONKEYCODE_API_URL:-http://localhost:8080/v1/chat/completions}"
MODEL="${MONKEYCODE_MODEL:-default}"

DIFF="$(git diff --cached || true)"
if [ -z "$DIFF" ]; then
  echo "No staged changes. Aborting." >&2
  exit 1
fi

PROMPT="You are a git expert. Write a Conventional Commit message for this diff. Use the format type(scope): subject. Keep subject under 50 characters. Do not add a body unless necessary. Diff:
$DIFF"

RESPONSE="$(curl -s "$API_URL" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg model "$MODEL" --arg prompt "$PROMPT" '{model:$model, messages:[{role:"user", content:$prompt}]}')" \
  | jq -r '.choices[0].message.content')"

# Extract the first line that matches the Conventional Commits format
GENERATED="$(echo "$RESPONSE" | grep -E '^(feat|fix|chore|docs|style|refactor|perf|test|build|ci|revert)(\(.+\))?: .+' | head -n1 || true)"

if [ -n "$GENERATED" ]; then
  echo "$GENERATED" > "$MSG_FILE"
  echo "Generated commit message: $GENERATED" >&2
else
  echo "AI did not produce a valid message. Edit manually." >&2
  exit 1
fi

Make it executable.

chmod +x .git/hooks/commit-msg

Step 3: Understand the flow

The hook runs after you write a commit message. It reads the message file. It checks the format. If the format is wrong, it builds a prompt from the staged diff. It sends the prompt to the AI server. It extracts a valid Conventional Commit from the response. It writes that message back to the file.

The grep pattern enforces the format. It allows types like feat, fix, and docs. It also allows an optional scope in parentheses.

Step 4: Test it

Stage a change and commit with an invalid message.

echo "test" > test.txt
git add test.txt
git commit -m "test"

The hook should replace the message with a generated one. You will see output like this.

Generated commit message: test: add test.txt

Check the log.

git log --oneline -1

You should see the generated message.

Step 5: Test with a valid message

Now commit with a valid Conventional Commit.

git commit --allow-empty -m "fix: resolve null pointer"

The hook should pass it through unchanged.

Step 6: Handle edge cases

The script has two failure modes. First, if there are no staged changes, it aborts. Second, if the AI returns no valid line, it exits with an error. In that case, git opens your editor so you can fix the message manually.

You can adjust the prompt. For example, ask for a body when the diff is large. Or restrict types to your project's convention.

Debugging the hook

If the hook does not run, check the file permissions. ls -l .git/hooks/commit-msg should show -rwxr-xr-x. If it does not, run chmod +x.

If the AI call fails, test the API manually.

curl -s "$MONKEYCODE_API_URL" \
  -H "Content-Type: application/json" \
  -d '{"model":"default","messages":[{"role":"user","content":"Say hi"}]}'

If you get a response, the server is fine. If not, check your URL and model name.

If the generated message is empty, check the prompt. The model may not follow the format. Add an example to the prompt.

PROMPT="You are a git expert. Write a Conventional Commit message for this diff. Example: fix(parser): handle empty input. Diff:
$DIFF"

This often improves output.

Limitations

The free tier has limits. Ten million tokens is generous, but not unlimited. Large diffs may exceed the context window. The AI may produce a message that does not match your team's style. You should review generated messages before pushing.

The script sends your diff to a remote server. Do not use it with proprietary code. If your project has strict compliance rules, use a private paid option.

Who should not use this

Do not use this if you need human-written messages for legal reasons. Do not use it for secrets or sensitive code. Do not use it as a substitute for code review.

Final check

Install the hook in a small repo. Run a few commits. Adjust the prompt to your style. That's it. You now have a free AI commit message writer.

Try it on your next feature branch. See if the messages match your team's conventions.

I Gave My Git History to a Free AI Bot. It Broke 7 Times in 3 Days.

Quinn Zhu — Sun, 23 Aug 2026 17:42:09 +0000

Last Tuesday, I built a bot. It reads my project's git log every night. It writes a plain-English summary of the day's changes. I hosted it on MonkeyCode's free server with the free token tier.

Three days later, I had an error-log folder and zero trust in "free" infrastructure.

This is the debugging log. Seven failures. Seven fixes. Each one taught me something about free AI infrastructure.

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

Free tier numbers change. Verify current terms in the dashboard before you depend on them.

The Setup

The bot is simple. A cron job runs at 23:00. It collects the last 20 commits. It sends them to the model. It posts the summary to a Slack webhook.

# summarize.py
import subprocess
import os
from openai import OpenAI

client = OpenAI(
    base_url=os.getenv("LLM_BASE_URL"),
    api_key=os.getenv("LLM_API_KEY"),
)

log = subprocess.run(
    ["git", "log", "--oneline", "-20"],
    capture_output=True, text=True
).stdout

response = client.chat.completions.create(
    model=os.getenv("LLM_MODEL"),
    messages=[
        {"role": "system", "content": "Summarize these commits for a non-technical stakeholder."},
        {"role": "user", "content": log},
    ],
)

print(response.choices[0].message.content)

Simple. Naive. Wrong in seven ways.

Failure 1: The Read Timeout

Symptom: The first run died after 60 seconds.

requests.exceptions.ReadTimeout: HTTPSConnectionPool(host='api...', port=443): Read timed out.

Diagnosis: The model took longer than the default 60-second timeout. Free-tier servers are not fast. The git log was long. The model had a lot to read.

Fix: Raise the timeout. Add retries with exponential backoff.

from tenacity import retry, stop_after_attempt, wait_exponential

@retry(stop=stop_after_attempt(3), wait=wait_exponential(multiplier=1, min=2, max=30))
def call_model(messages):
    return client.chat.completions.create(
        model=os.getenv("LLM_MODEL"),
        messages=messages,
        timeout=120,
    )

Verify: Run the script. Watch it survive past 60 seconds.

Failure 2: Markdown-Wrapped JSON

Symptom: The bot printed a JSON object wrapped in a code fence.

```json
{"summary": "..."}
```

Diagnosis: The model decided to be helpful and add syntax highlighting. My parser expected raw JSON.

Fix: Strip code fences before parsing.

import re
import json

def extract_json(text):
    match = re.search(r"```

(?:json)?\s*(.*?)\s*

```", text, re.DOTALL)
    if match:
        return json.loads(match.group(1))
    return json.loads(text)

Verify: Feed it a fenced response. Confirm it parses.

Failure 3: The 429 Wall

Symptom: Day two. The bot stopped.

openai.RateLimitError: Error code: 429 - quota exceeded

Diagnosis: I burned the free token quota in one night. The git log had 20 commits with long messages. Each call consumed thousands of tokens. I never checked the usage dashboard.

Fix: Truncate the input. Count tokens before sending.

log = subprocess.run(
    ["git", "log", "-5", "--format=%h %s"],
    capture_output=True, text=True
).stdout[:2000]

Five commits. Two thousand characters. Enough for a useful summary.

Verify: Check the usage dashboard the next morning. Confirm the drop.

Failure 4: The OOM Kill

Symptom: The process vanished. No error in the log. Just a Killed line.

Diagnosis: The free server ran out of memory. The OOM killer targeted my Python process.

Fix: Limit memory. Keep the bot stateless.

ulimit -v 512000  # 512 MB virtual memory

Read from disk. Write to disk. Do not hold data in memory.

Verify: Run dmesg | grep -i oom. Confirm no new kills.

Failure 5: The Timezone Trap

Symptom: The summary said "yesterday" when it meant "today".

TypeError: can't compare offset-naive and offset-aware datetimes

Diagnosis: Git timestamps are timezone-naive. Python's datetime.now() on the server was timezone-aware. Comparing them crashed the script.

Fix: Force UTC everywhere.

from datetime import datetime, timezone

now = datetime.now(timezone.utc)

Verify: Run the bot at 23:59. Confirm the date rolls over correctly.

Failure 6: The Cron Env Void

Symptom: Cron ran the job. The script failed. No output.

Diagnosis: Cron does not load your shell profile. The API key was not set.

Fix: Export variables inside the cron command.

0 23 * * * cd /home/user/bot && LLM_API_KEY=... LLM_BASE_URL=... LLM_MODEL=... /home/user/bot/venv/bin/python summarize.py >> bot.log 2>&1

Verify: Check the log file. Confirm output appears.

Failure 7: Context Length Exceeded

Symptom: A 400 error.

openai.BadRequestError: Error code: 400 - context_length_exceeded

Diagnosis: One commit message was enormous. A merge commit with a 3,000-word description. It pushed the total over the model's limit.

Fix: Cap each commit message.

commits = [c[:200] for c in commits]

Verify: Send the longest commit. Confirm it fits.

What I Learned

Free infrastructure is not bad. It is just honest. It shows you every assumption you made about reliability.

Timeouts are real. Retry.
Models add formatting. Strip it.
Quotas run out. Count tokens.
Memory is limited. Keep it small.
Timezones lie. Use UTC.
Cron has no env. Set it explicitly.
Context has a ceiling. Trim early.

Who Should Not Do This

Do not run this for production. Do not send sensitive commit messages to a free model. Do not expect a free server to survive a traffic spike.

Use this setup for personal projects. Use it to learn. Use it to build a habit of observability.

Try It

Build a small bot. Break it on purpose. Read every error. Fix each one.

MonkeyCode's free tier is a good place to start. The dashboard shows current limits. The same code works with any OpenAI-compatible provider.

Start with one failure. Let the error log teach you the rest.

Why Generated Tests Fail: A Field Guide to 5 Failure Modes

Quinn Zhu — Sat, 22 Aug 2026 15:32:23 +0000

Generated tests fail in predictable ways. Once you see the pattern, you can fix it. This guide covers five failure modes. Each has a code example and a fix. The goal is simple: turn a pile of broken drafts into a usable test baseline.

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

Why this matters

Model-generated tests rarely pass on the first run. That is not the model's fault. Tests need context. The model only sees the source you give it. The failure modes are finite. Learn them, and you can batch-fix most of your generated suite.

This guide assumes you have a generation pipeline. I use MonkeyCode's free model access to generate tests. The free server runs pytest. The free tier includes a 10M token allowance. One generation costs roughly 800 tokens. You can run thousands of iterations.

Your pipeline probably looks like this:

import json
import os
import urllib.request

def generate_test(func_name, source):
    prompt = f"""Write one pytest test for {func_name}.
Source:
{source}
Return only Python code."""
    payload = {
        'model': os.environ['MONKEYCODE_MODEL'],
        'messages': [{'role': 'user', 'content': prompt}],
    }
    req = urllib.request.Request(
        os.environ['MONKEYCODE_BASE_URL'],
        data=json.dumps(payload).encode(),
        headers={
            'Authorization': f"Bearer {os.environ['MONKEYCODE_API_KEY']}",
            'Content-Type': 'application/json',
        },
    )
    with urllib.request.urlopen(req, timeout=30) as resp:
        data = json.load(resp)
    return data['choices'][0]['message']['content'].strip()

Failure Mode 1: The Overly Strict Assertion

Models love exact matches. Real functions return timestamps, random IDs, or floats. Exact assertions fail immediately.

A typical model output:

def test_format_report():
    assert format_report({"name": "Alice"}) == "Report: Alice at 2026-08-22 10:00:00"

The problem: the timestamp is generated at runtime. The fix: assert substrings.

def test_format_report():
    result = format_report({"name": "Alice"})
    assert "Alice" in result
    assert result.startswith("Report:")

Detection signal: the failure message shows a string mismatch, but only the dynamic part differs.

Failure Mode 2: The Missing Environment

The model does not know your code needs config files, env vars, or a database. It generates a direct call. The function crashes because the environment is absent.

A typical model output:

def test_load_config():
    config = load_config()
    assert config["timeout"] == 30

The problem: load_config() reads config.yaml, but the test directory has no such file. The fix: add a fixture.

def test_load_config(tmp_path, monkeypatch):
    (tmp_path / "config.yaml").write_text("timeout: 30\n")
    monkeypatch.chdir(tmp_path)
    assert load_config()["timeout"] == 30

Detection signal: FileNotFoundError, KeyError, or connection errors.

Failure Mode 3: The Wrong Argument Guess

The model sees process(data, mode) and guesses data is a string. In reality, data is a list of dicts. The test dies at the entry point.

A typical model output:

def test_process():
    assert process("hello", "fast") == ["hello"]

The problem: process expects data to be list[dict]. The fix: infer types from the source before generating.

def test_process():
    data = [{"id": 1, "text": "hello"}]
    result = process(data, "fast")
    assert result[0]["id"] == 1

Detection signal: TypeError or AttributeError on the first line of the test. Give the model more source context to reduce this mode.

Failure Mode 4: The Hidden Global State

Module-level variables, caches, or singletons. The model cannot see them. It assumes the function is pure. The test passes alone and fails in a full run.

A typical model output:

def test_get_counter():
    assert get_counter() == 0

The problem: get_counter() reads module-level _counter. The first call changes it to 1. The fix: reset state.

def test_get_counter(monkeypatch):
    import mymodule
    monkeypatch.setattr(mymodule, "_counter", 0)
    assert mymodule.get_counter() == 0

Detection signal: the test passes in isolation and fails with the full suite. This is the sneakiest mode.

Failure Mode 5: The Empty Assertion

The most dangerous one. The test passes but verifies nothing. The model generates assert result is not None. A function returning None sails through.

A typical model output:

def test_parse():
    result = parse("a=1")
    assert result is not None

The problem: an empty dict also passes. The fix: assert concrete values.

def test_parse():
    result = parse("a=1")
    assert result == {"a": "1"}

Detection signal: coverage rises, but mutation testing kills everything. That is false confidence.

The classification workflow

Do not review generated tests one by one. Run them first. Then classify.

pytest test_generated.py --tb=short --no-header -q

Map each failure to a mode. Each mode has a standard fix. Apply them in bulk.

Failure mode	Signal	Fix
Overly strict assertion	String mismatch	Use substring assertions
Missing environment	FileNotFoundError	Add a fixture
Wrong argument guess	TypeError	Correct the arguments
Hidden global state	Passes alone, fails together	Reset state
Empty assertion	Passes but verifies nothing	Strengthen the assertion

What to generate on

Not every function deserves generated tests. Use this decision table.

Function trait	Generate?	Why
Pure function, simple args	Yes	The model guesses correctly
Clear input/output types	Yes	Assertions are easy to write
Depends on IO or network	No	Too many environment traps
Depends on global state	No	Tests become flaky
Security-critical logic	No	Needs human review

Limitations

This guide covers common failure modes. Your codebase may produce new ones. The table is not exhaustive.

Generated tests are drafts. They do not replace hand-written tests. They give you a starting point.

The free token allowance is generous but not infinite. Watch your usage dashboard.

The honest bottom line

Generated test failures are predictable. Predictable means fixable. Fixable means you can turn AI drafts into a real baseline.

Start with one pure-function file. Run the pipeline. Classify failures with this guide. Most fixes take a few lines. Your future self will thank you.

MonkeyCode Free Tier: A 20-Minute Setup with a Check at Every Step

Quinn Zhu — Fri, 21 Aug 2026 13:28:16 +0000

Free tiers are underrated. Everyone wants the biggest model. Nobody wants the bill. A free quota forces you to build small and measure everything. That constraint is a feature.

This tutorial sets up MonkeyCode's free model access and free server option. You go from zero to a verified request in about 20 minutes. Every step has a check. The setup costs nothing.

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

Why verify at all

Everyone debates how to measure AI output. Most people never measure their own requests. A smoke test gives you three facts. The endpoint is reachable. The key is valid. The model returns tokens. That is enough to start. It is not enough to benchmark.

What you are setting up

MonkeyCode is an open source project. You can read the source and check the docs yourself. The free tier has two parts:

Free model access. At the time of writing, the tier advertises 10,000,000 tokens (10M).
A free server option. You do not need a GPU or a cloud VM. The server side handles the model access.

A weak laptop is fine. The heavy work happens elsewhere. I will not invent specs here. Quotas change. Endpoints change. Check the official docs for current limits.

Prerequisites

You need three things:

A MonkeyCode account. Signup is free.
A terminal with curl and jq.
Five minutes of patience.

That is the whole list.

Step 1 — Create the account and export the key

Then export three values:

export MONKEYCODE_KEY="paste-your-key-here"
export MONKEYCODE_ENDPOINT="https://paste-endpoint-from-dashboard"
export MONKEYCODE_MODEL="model-id-from-dashboard"

Check: echo "$MONKEYCODE_KEY" prints a non-empty string.

Never hardcode the key in a script. Use the environment variable.

Step 2 — Smoke-test the endpoint

Save this as mc-smoke.sh:

#!/usr/bin/env bash
set -euo pipefail

ENDPOINT="${MONKEYCODE_ENDPOINT:?Set MONKEYCODE_ENDPOINT}"
API_KEY="${MONKEYCODE_KEY:?Set MONKEYCODE_KEY}"
MODEL="${MONKEYCODE_MODEL:?Set MONKEYCODE_MODEL}"

PAYLOAD=$(cat <<JSON
{"model":"$MODEL","messages":[{"role":"user","content":"Reply with exactly: OK"}]}
JSON
)

curl -s -o /tmp/mc_body.json -w '%{http_code}' \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d "$PAYLOAD" \
  "$ENDPOINT/chat/completions" > /tmp/mc_status.txt

echo "HTTP status: $(cat /tmp/mc_status.txt)"
echo "Reply: $(jq -r '.choices[0].message.content' /tmp/mc_body.json)"
echo "Usage: $(jq -c '.usage' /tmp/mc_body.json)"

Run it:

chmod +x mc-smoke.sh
./mc-smoke.sh

Check: HTTP status is 200. The reply is OK. The usage object shows real token counts.

If curl itself fails, check your network and the endpoint URL. This script assumes an OpenAI-style chat completions shape. If your endpoint differs, adjust the path and the jq fields. The dashboard shows the exact values.

Step 3 — Prove the server is doing the work

The free server option means the model access runs remotely. Prove it. Open a fresh cloud shell. That machine has no local model runtime. Run the smoke test there.

export MONKEYCODE_KEY="paste-your-key-here"
export MONKEYCODE_ENDPOINT="https://paste-endpoint-from-dashboard"
export MONKEYCODE_MODEL="model-id-from-dashboard"
./mc-smoke.sh

Check: the request succeeds on a machine with nothing installed. The model access is server-side. Your laptop is only a client.

That is the value of the free server option. No local GPU. No local setup.

Step 4 — Track the 10M token budget

Free quotas disappear quietly. Requests just start failing one day. Track the budget from day one.

Log the tokens from each request:

jq '.usage.total_tokens' /tmp/mc_body.json >> "$HOME/.mc_usage.log"

Save this as mc-track.sh:

#!/usr/bin/env bash
LOG="${HOME}/.mc_usage.log"
QUOTA=10000000
touch "$LOG"

TOTAL=$(awk '{s+=$1} END {print s+0}' "$LOG")
echo "Tokens used: $TOTAL / $QUOTA"

if [ "$TOTAL" -ge $((QUOTA * 80 / 100)) ]; then
  echo "Warning: you have used 80% or more of the free quota."
fi

Run it after every session:

./mc-track.sh

Check: the number grows after each request. The warning fires at 8,000,000 tokens.

The log is plain text. You can read it, grep it, or plot it. No database required.

Step 5 — Use it on a real task

Point any client that supports custom base URLs at the endpoint. Set the base URL to $MONKEYCODE_ENDPOINT. Set the key. Pick the model.

Start small. Summarize a function. Explain a stack trace. Generate a test case. Each task costs a few hundred tokens. At that rate, 10M tokens last a long time.

Check: a real task completes. The tracker shows the exact cost.

Common failures

Symptom	Likely cause	Fix
HTTP 401	Wrong or expired key	Recreate the key and re-export it
HTTP 404	Wrong endpoint path	Copy the exact path from the dashboard
Model error	Wrong model id	Use the exact id from the dashboard
Empty reply	The response contains an error	Read the `error` field in `/tmp/mc_body.json`
Quota error	Free tokens exhausted	Check the docs for your options

Who should skip this

This setup is for experiments, not production.

Skip it if you need an SLA. Free tiers have no uptime guarantees.
Skip it if you run heavy production traffic. 10M tokens vanish fast.
Skip it if you benchmark for a paper. A shared free endpoint is not a controlled environment.

This is a smoke test, not a benchmark. Use it to learn your own token habits. Use it to validate a workflow. Do not use it to publish conclusions about model quality.

Try it

The setup takes 20 minutes. The verification takes five. The cost is zero. Give the free tier a shot this week. You will learn more about your own usage than about the model. That alone is worth the time.