Visible Thinking in AI-Assisted Development¶

Visible thinking — meaningful commits, signal-rich PRs, and clear branch naming — becomes the primary quality differentiator once AI compresses code production.

The shift¶

AI coding tools compress the time between idea and implementation: in a controlled GitHub study, developers using Copilot finished the same task in an average of 1 hour 11 minutes, against 2 hours 41 minutes without it — 55% faster (GitHub: Quantifying GitHub Copilot's Impact on Developer Productivity and Happiness). Code production is no longer the bottleneck. What stays scarce is the reasoning trail — why you made a decision, what alternatives you considered, what constraints shaped the solution. This is the same replayable record that trajectory logging captures from agent runs.

Visible thinking means documenting intent and rationale across the development lifecycle. It makes work reviewable, maintainable, and trustworthy. GitHub puts it directly: "Speed and control aren't trade-offs. They reinforce each other" (GitHub Blog: Speed Is Nothing Without Control).

Quality signals across the lifecycle¶

Issues as specifications¶

Capture the problem, success criteria, constraints, and risks in the issue before you engage an agent. A well-structured issue guides the AI toward the right solution and creates a reviewable record of intent.

Branch naming¶

Use meaningful branch names that convey purpose. When agents generate branches, enforce a convention that shows scope at a glance, for example feature/add-oauth-flask or fix/null-check-user-service. Generic names like agent-fix-1 lose signal.

Meaningful commits¶

Write commit messages that narrate reasoning, not just describe changes. Instead of Added dark mode toggle, explain the decision: chose localStorage for persistence to avoid server dependency (GitHub Blog: Speed Is Nothing Without Control).

When you work with agents, review and rewrite AI-generated commit messages before you push. The commit log is the permanent reasoning record. It outlasts the chat session that produced the code.

Signal-rich pull requests¶

Structure PR descriptions to answer three questions (GitHub Blog: Speed Is Nothing Without Control):

Why: the problem or opportunity that motivated the change.
What changed: a concrete description of the implementation approach.
Trade-offs: the alternatives you considered and why you chose this path.

This structure matters more when AI generates the code, because the reviewer cannot infer reasoning from the implementation alone. The PR description bridges the gap between what the agent produced and why the developer accepted it — and PR description style is itself a lever on merge rates.

Structured prompting as visible intent¶

How you prompt an agent is itself a form of visible thinking. GitHub recommends a structured framework (GitHub Blog: Speed Is Nothing Without Control):

Goals: state the outcome, not the action ("improve readability while preserving functionality" rather than "refactor this file").
Constraints: specify boundaries ("no third-party dependencies," "no breaking changes").
Context: reference related files, architecture decisions, and existing conventions — much of which a project's instruction-file ecosystem already encodes.
Output format: define the expected shape of the result.

Save prompts alongside code — in commit messages, PR descriptions, or instruction files. This preserves decision context that would otherwise vanish when the chat session ends. It mirrors Anthropic's guidance to "prioritize transparency by explicitly showing the agent's planning steps" (Anthropic: Building Effective Agents), and Claude Code best practices recommend checking CLAUDE.md into git so constraints persist across sessions (Claude Code Best Practices).

Anti-patterns¶

Accepting defaults: merging AI-generated commits and PRs without editing their messages throws away the chance to document reasoning.
Reasoning-free velocity: shipping code faster without documenting why you built it that way creates a codebase that is fast to produce and slow to maintain. The same GitHub study found task completion rates rose from 70% to 78% with Copilot (GitHub: Quantifying GitHub Copilot's Impact on Developer Productivity and Happiness) — a gain in whether the code shipped, not in whether anyone could later explain why it was built that way.
Opaque agent sessions: running agents without recording the prompts, constraints, or goals that shaped the output makes the work unreviewable after the fact.

Example¶

This pair of commit messages shows the difference between a default AI-generated message and one rewritten to document reasoning.

# Default AI-generated commit — describes the change, not the decision
git commit -m "Add dark mode toggle"

# Rewritten to capture reasoning — explains why, what constraint shaped the choice
git commit -m "feat(ui): add dark mode toggle using localStorage

Chose localStorage over a user preference API to avoid adding a server
dependency. Follows the no-new-endpoints constraint from the issue spec."

A matching PR description applies the same structure to the pull request body:

## Why
Users on low-brightness displays reported eye strain; the issue (#412) set
no-new-endpoints as a hard constraint.

## What changed
- Added `useDarkMode` hook that reads/writes `localStorage('theme')`
- Toggled `data-theme` attribute on `<html>` to drive CSS variables

## Trade-offs
Server-side persistence (so preference follows the user across devices) was
ruled out by the constraint. Accepted trade-off: preference resets on new
devices.

The reasoning recorded in the commit and PR outlasts the chat session. A reviewer, or a future maintainer, can reconstruct why you chose localStorage without access to the original prompt.

When this backfires¶

Visible thinking assumes the documentation overhead is recoverable — that the time you spend writing clear commit messages and PR descriptions costs less than the time it saves later in review and the distinct maintenance footprint of agent-generated code. That assumption breaks down in several situations:

Extreme time pressure with short-lived code: throwaway scripts, hotfixes with an immediate rollback plan, or spike branches deleted after a demo rarely justify detailed commit narration. The reasoning record has no audience.
AI-generated documentation accepted uncritically: when developers prompt agents to generate commit messages and PR descriptions without review, the visible thinking artifacts are present but meaningless. They document what the agent guessed the reasoning was, not the actual constraints and trade-offs. Agent transcript analysis recovers the real trail when you cannot trust the narration.
Context saturation in large teams: as codebases grow and commit volume rises, the signal-to-noise ratio of commit history degrades. Teams that enforce verbose commits without pruning or tagging conventions often find the log unsearchable. The documentation exists but cannot be found.
Misaligned tooling: repositories using squash-merge strategies collapse all commit reasoning into a single PR description, which raises the stakes on PR description style. You lose branch-level commit discipline, which makes per-commit narration pointless unless PR descriptions absorb that detail.

Key Takeaways¶

AI shifts the quality bottleneck from code production to reasoning documentation — commit messages, PR descriptions, and issue specifications are where experienced developers add irreplaceable value.
Structure PR descriptions around why, what changed, and trade-offs to bridge the gap between AI-generated code and human review.
Treat structured prompts as artifacts worth preserving — they capture the intent and constraints that shaped each implementation decision.