The Ultimate Claude Code Setup for an Existing Codebase

Start with the repository

This setup is for an engineer changing an existing system. You should be able to point to the current behavior, the decision that constrains the change, and the check that would catch a regression. Those are the criteria for this setup.

Follow the Claude Code Quickstart for the installer that matches your operating system. In a terminal, run claude --version, change into your repository, and run claude. Follow the sign-in prompts if needed. These steps are for a local terminal session.

Read the existing CLAUDE.md before editing it. If the repository needs one, keep the project file short and record the local build, focused test, and broader test commands. Run a relevant command yourself so you know what a useful failure looks like. Claude Code’s project instructions documentation describes where those files load.

• Working directory and instructions. Open the repo and confirm which commands and conventions apply.
• Task brief. Write the requested behavior, attach the decision that constrains it, and note any open question.
• Verification. Choose checks for the new behavior and the existing behavior that must survive.

Connect one source when history lives elsewhere

If the decision is already in the repo or you can attach the original record to the task, start there. For history in an approved Shifu source, connect Claude Code through MCP and retrieve the relevant decision before editing.

The published Shifu connector README describes its local setup for macOS and Linux. With Node.js 20 or later, run the command below. Use your Claude Code connection key when prompted. This connects retrieval to already saved work. The setup for adding a new source is a separate choice.

For a new work-file source, the same connector offers the local wizard through npx --yes @useshifu/coding-harness@0.3.38 onboard --harness claude_code. Choose one permitted folder and review the file and history scopes before starting. Enabled folder files are uploaded as provided for server-side processing. For the example below, use the synthetic decision record rather than a real partner document.

Start a new Claude Code session after connecting and use /mcp to check the server status. Confirm that the approved record is available before relying on it. The native path is to hand the assistant the decision record directly.

npx --yes @useshifu/coding-harness@0.3.38 mcp-setup --harness claude_code --mcp-url https://api.useshifu.com/mcp

Plan the retry change

The request is to increase automatic retries from one to three for transient failures. The fictional decision record below governs one partner. If you try the connected workflow, ask Claude Code to look up ADR-007 in Shifu, return the source and its scope, and identify any conflicting decision. Read the original decision and confirm that it still applies.

Ask one question that could change the plan. A Grill Me-style question for this example is “Should the manual-recovery partner keep zero retries after this change?” The engineer’s answer in this walkthrough is yes. Count three additional attempts after the initial failure for a standard partner.

Write the acceptance checks before editing. Standard partner with a transient failure gets three retries. Manual-recovery partner with a transient failure gets zero. Permanent failure gets zero. The fixture exercises the permanent case with a standard partner.

Illustrative decision record ADR-007 · Manual recovery partner

Status: accepted in this fictional example and confirmed for the retry change.
The manual-recovery partner handles failed operations through its own recovery
process. It must receive zero automatic retries, including transient failures.
Permanent failures receive zero automatic retries for every partner.

New request: increase automatic retries from one to three for transient failures.
The existing exemption remains in effect. "Three" means additional attempts
after the initial failure, not total attempts.

Copy the Python fixture

Save this complete block as retry_example.py. The script uses Python 3.13 and the standard library. It runs one suite against three policy functions so you can see which check each change affects.

"""Illustrative retry policy, with three versions tested by one suite."""

from __future__ import annotations

import argparse
import unittest
from collections.abc import Callable

RetryLimit = Callable[[str, str], int]


def baseline_retry_limit(partner: str, failure: str) -> int:
    """Retry transient failures once, except for the manual recovery partner."""
    if failure != "transient" or partner == "manual-recovery":
        return 0
    return 1


def blanket_retry_limit(partner: str, failure: str) -> int:
    """An incomplete patch that forgets the partner exemption."""
    return 3 if failure == "transient" else 0


def revised_retry_limit(partner: str, failure: str) -> int:
    """Retry transient failures three times and preserve the exemption."""
    if failure != "transient" or partner == "manual-recovery":
        return 0
    return 3


def verify(policy: RetryLimit) -> bool:
    class RetryPolicyTest(unittest.TestCase):
        def test_standard_partner_gets_three_retries(self) -> None:
            self.assertEqual(policy("standard", "transient"), 3)

        def test_manual_recovery_partner_is_exempt(self) -> None:
            self.assertEqual(policy("manual-recovery", "transient"), 0)

        def test_permanent_failure_is_not_retried(self) -> None:
            self.assertEqual(policy("standard", "permanent"), 0)

    suite = unittest.defaultTestLoader.loadTestsFromTestCase(RetryPolicyTest)
    return unittest.TextTestRunner(verbosity=2).run(suite).wasSuccessful()


if __name__ == "__main__":
    policies = {
        "baseline": baseline_retry_limit,
        "blanket": blanket_retry_limit,
        "revised": revised_retry_limit,
    }
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("version", choices=policies)
    args = parser.parse_args()
    raise SystemExit(0 if verify(policies[args.version]) else 1)

Build from a failing check

From the folder where you saved the file, run the commands below one at a time. Start with baseline. Its one-retry result should fail the new standard-partner check. The two preserved behaviors should pass. This is the starting evidence before changing the policy.

The blanket version changes every transient failure to three retries and loses the partner exemption. The revised version keeps the existing failure and partner guards, then changes the standard transient limit from one to three.

python3 retry_example.py baseline
python3 retry_example.py blanket
python3 retry_example.py revised

Verify with the same suite

The output below is from running the supplied fixture with Python 3.13.6. Read the assertion and exit status together. The first two executions fail for different reasons.

In review, trace the manual-recovery assertion back to ADR-007. Then trace the standard retry assertion to the new request. Inspect the diff and run the repository’s relevant checks before deciding whether a real change is ready.

The Python fixture uses invented partners and an isolated policy function. Its output covers three checks in that example. The connected Shifu, Claude Code, and skill steps describe a workflow you can try on your own task.

Use the same checklist on your change

Before editing, bring one relevant decision and the command that can test it. At review, hand over the source, the diff, and the actual check output. If the decision is missing or disputed, resolve it before changing the dependent behavior. The skills and plugins companion helps you decide whether a repeated step is worth packaging.