Skip to content

Tips & tricks

The big picture: A handful of Claude Code mechanics worth knowing on purpose — permission modes, Plan mode — plus a CI trap (gates that read the GitLab issue tracker) and vetted links for going deeper than this site can.

Why it matters: These are the controls you’ll touch dozens of times a day. Knowing them well is the difference between babysitting a session and supervising one.

Shift+Tab is identical on macOS and Windows/Linux — there’s no platform-specific bind — but it cycles permission modes rather than toggling a single switch: Manual → Accept Edits → Plan → Auto → back to Manual. Auto sits last in the cycle, so reaching it from Manual takes three presses, not one. (On a Pro, Max, or Team plan, a new terminal session already starts in auto mode as of August 2026 — check permissions.defaultMode in .claude/settings.json if a session isn’t starting where you expect.) That’s also why the day-in-the-life setup passes claude --permission-mode auto at startup rather than relying on the toggle: one flag beats three keystrokes per new worktree terminal, and it’s the only way in on plans — Enterprise, API-key accounts — whose built-in default is still Manual.

This is worth reaching for, not just a convenience: Anthropic’s own numbers are why. Their classifier caught more dangerous actions than developers did approving prompts by hand, held up under third-party red-teaming, and cut serious unintended harm from 6.3% of manually-approved sessions to 2.4% of auto-mode sessions at production severity (Auto mode is now the default, Running auto mode in production). Internally it’s the same shift this template’s worktree setup is built around — less turn-by-turn approval, more monitoring: max consecutive tool calls per session rose 116% and human turns per transcript fell 33% in one internal study (How AI is transforming work at Anthropic), and session length before stopping nearly doubled in three months in another (Measuring AI agent autonomy in practice). If the classifier blocks something routine over and over, that’s usually missing context about your infrastructure, not a wrong call — /feedback reports it, and an admin can add trusted repos/hosts via autoMode.environment.

Enter it with Shift+Tab or by prefixing a single prompt with /plan. Claude reads and explores but won’t edit until you approve. When the plan is ready:

  • “Yes, and use auto mode” approves it and goes straight into auto-mode execution (see above) — the fastest path from design gate to implementation.
  • Ctrl+G opens the proposed plan in your default text editor so you can rewrite it by hand before Claude proceeds, rather than only approving or asking for changes in-chat.

This is the mechanism behind the “plan before code” row in the best-practices table, and behind the architect → ux-design gates in the fast-path table in CLAUDE.md — those agents produce the plan; Plan mode is how you review it before anything gets edited.

Any gate that looks up issue state over the GitLab API (an MR-description follow-up check, a known-issues freshness check, a suppression-marker check) can fail in ways that look like something else. The same trap has hit three repos:

  • trueppm/trueppm#4452 — docs:known-issues-freshness turned main red with HTTP 429, and each retry failed on a different set of issues. That is a rate budget running out, not bad content.
  • macrodream/blueprint#123 — check-mr-followups.sh had the identical shape (fixed in !96).
  • visiban/visiban#1694 — suppressions-check was silently blind. It sent a JOB-TOKEN header, which this endpoint rejects with 401, and treated the failure as “unknown, non-blocking”. It stayed green only because no marker existed yet.

The rules that prevent all three:

  1. Anonymous calls share one per-IP budget. Every job on a self-hosted runner leaves through one egress IP, and GitLab.com’s anonymous limit is its lowest tier. A gate that makes one GET per reference exhausts it.
  2. Batch, do not loop. GET /projects/:id/issues?iids[]=1&iids[]=2 (and so on, up to 100 per page) resolves every reference in one call. Use the shared reader scripts/lib/gitlab-issues.sh (gitlab_issue_states), which does this and prints one iid<TAB>state<TAB>title line per issue. Never write a per-issue curl loop in a new gate.
  3. Retry 429, honoring Retry-After, bounded, then decide the policy out loud. The helper retries 429, 5xx and network errors up to GITLAB_ISSUES_MAX_ATTEMPTS times (default 5), waits Retry-After when present (otherwise exponential backoff), caps each wait at 60 seconds, then returns status 2. The caller picks the policy: check-mr-followups.sh fails closed, with MR_FOLLOWUPS_ALLOW_UNRESOLVED=1 as an explicit escape hatch. It admits a missing issue as well as a confidential one, because GitLab answers both the same way; it is meant for a single job run, not a standing CI variable. Whichever you choose, make “could not read the tracker” distinguishable from a misconfiguration and from a real finding.
  4. Never send JOB-TOKEN to the Issues API. It is not a job-token endpoint, and any JOB-TOKEN header turns a public project’s anonymous 200 into a 401. A fail-open gate turns that into permanent, silent blindness.
  5. Use ISSUES_API_TOKEN for the authenticated limit. It is the shared fallback for per-script variables such as MR_FOLLOWUPS_TOKEN. On GitLab.com, project and group access tokens are a paid-tier feature (the Free plan answers HTTP 400 “User does not have permission to create project access token”), so on Free it is usually a personal read_api token, which reads everything that user can see, including private sibling repos. Scope it accordingly and store it masked. Protected plus masked gives main and scheduled pipelines the token while MR pipelines stay anonymous, which batching plus retry make sufficient for a public tracker. On a private tracker an anonymous lookup returns 401, so the token must not be protected, or MR-pipeline gates cannot read issues at all. The comments in .gitlab-ci.yml and scripts/lib/gitlab-issues.sh give the same advice. If a lookup with the token gets a 401, the helper warns and retries anonymously, so an expired token degrades instead of turning the pipeline red.
  6. A confidential issue looks missing. GitLab leaves it out of the list response (and answers 404 on the single read) for an anonymous caller and for a token whose user is below Reporter on the project, exactly as for an issue that does not exist. A gate cannot tell the two apart, so it must not report the reference as untracked work: check-mr-followups.sh reports it as UNRESOLVED (exit 2). If follow-ups may be confidential, give the token to a Reporter-or-higher member (macrodream/blueprint#337).
  7. Know the tell. A fail-closed tracker gate that fails on different issues each retry is rate-limited, not wrong. A fail-open one that never warns may be getting a 401 on every call. Probe it by comparing a request sent with -H "JOB-TOKEN: x" against the same request with no header, both aimed at …/issues/1.
  8. Keep pipes out of the check. Under set -o pipefail, … | head and … | grep -q can end the producer with SIGPIPE and report a present match as missing. Capture the output into a variable first, then test it.

Nobody should have to reverse-engineer this template’s conventions from the diff of a generated migration. These are the primary sources this site’s own conventions are drawn from.

Claude Code

Resource What it’s for
Claude Academy — Claude Code 101, Claude Code in Action Anthropic’s own free, self-paced courses (Skilljar-hosted). 101 covers the agentic loop, context, and the explore → plan → code → commit workflow; in Action covers steering long hands-off sessions, hooks, headless mode, and packaging skills for a team — the material this template’s harness assumes
Full course catalog The broader Anthropic Academy catalog beyond Claude Code — AI Fluency, MCP, API fundamentals, cloud-platform tracks
Claude Code docs Reference for everything this site only summarizes: permission modes, hooks, skills, subagents, settings
Claude Code best practices Anthropic’s own engineering write-up — the source for most of the best-practices table
Claude Cookbooks Copy-able recipes for building with Claude beyond Claude Code itself (tool use, RAG, evals, prompt caching) — useful once a project’s own product also calls the API

Git & GitLab — this template assumes comfort with both; neither is optional once you’re past /kickoff

Resource What it’s for
Pro Git The free, official Git book — start here for branching, merging, and rebasing if scripts/wt’s worktree model feels unfamiliar
git-scm.com/docs and gittutorial Git’s own command reference and shortest official tutorial
Learn Git — GitLab Docs GitLab’s guided tutorials (first commit, rebase, rewriting commit messages, remotes) using the same glab-flavored workflow this template’s Git conventions assume