Claude Code configuration and continuous integration

Text description

• Guidance: Prompts and CLAUDE.md provide task and project context that can influence behavior.
• Enforcement: Permissions, repository controls, and backend systems determine what the environment permits.

Episode Four treats Claude Code as a governed engineering environment rather than simply a convenient place to ask for code. A repository is the version-controlled home of a software project, where code, tests, configuration, and their shared change history live together. To keep the examples concrete, Harbour Resolution is a fictional financial services company, not a claim about any real deployment. The central distinction is simple: guidance can influence what Claude does, while enforcement determines what the surrounding system will actually permit. A prompt is the task description given to Claude, and a file named CLAUDE.md provides persistent background instructions that can accompany prompts across work in a project.

That background, often called context, can describe architecture, build commands, testing conventions, naming patterns, repository boundaries, and hazards worth noticing. At fictional Harbour Resolution, a new engineer might open a repository and find guidance explaining which service owns customer records and which command runs its approved tests. The file helps Claude navigate the project consistently, but it works best when it contains information that is relevant to recurring engineering tasks. Short is useful here. An oversized instruction file competes with the current code and task for attention, rather like covering a workbench with every manual in the building, although software context is less predictable than physical clutter.

Text description

• Organisation: Supplies broad expectations that apply across projects.
• Repository: Adds design-specific instructions and shared project truth.
• User: Captures recurring personal preferences without overriding shared rules.
• Matching path: Activates relevant guidance when work touches specified files or directories.

Detailed material can remain in maintained documentation and be linked or imported when needed, leaving the always-loaded guidance focused. Configuration can be layered so an organisation supplies broad expectations while a repository adds instructions specific to its own design. User-level guidance can capture a person's recurring preferences, but personal convenience should not silently override shared project truth or organisational policy. A path-specific rule is guidance that becomes relevant only when work touches matching files or directories. In a hypothetical Harbour Resolution payment change, opening the payments directory might bring in instructions requiring transaction tests and warning against direct database writes. The engineer would see Claude acknowledge that warning and propose using an approved service interface instead of writing directly to a table.

The tempting mistake is to treat that acknowledgment as proof that direct writes are impossible. CLAUDE.md is still contextual guidance, so a conflicting prompt, misunderstood instruction, or unexpected reasoning path can produce a different suggestion. Settings configure how the client behaves, while permissions specify which tools or operations it may attempt. Authentication establishes which user or system identity is acting, whereas authorization determines what that authenticated identity is allowed to do. A branch is an independent line of version-controlled changes, and merging incorporates changes from one branch into another. A valid login therefore does not imply permission to edit every file, run every command, merge changes into every branch, or reach a production database.

Non-negotiable boundaries need constrained permissions and tests, plus enforcement in repository and backend systems. A protected branch is a server-enforced merge boundary that can require checks or reviewers even when a local coding session says the work is complete. These controls reduce risk without promising absolute safety, because their strength still depends on correct configuration, coverage, and operation. Claude Code can also maintain auto memory in configurations that support it, allowing useful recurring facts to carry across sessions. Memory is handy for a stable preference, but an unreviewed memory can become stale, conflict with the repository, or quietly accumulate guesses. Important engineering truth belongs in version-controlled documentation and configuration where people can review changes, identify ownership, and restore an earlier state.

Text description

• Custom command: Expands a selected name into a familiar bounded request or workflow.
• Skill: Packages reusable instructions, knowledge, supporting files, workflow steps, and permitted tools.

A Skill is a reusable package of instructions, knowledge, supporting files, and workflow steps that Claude can load when relevant or invoke directly. A narrow Skill saves the team from restating a complex process while keeping the process visible enough to inspect and maintain. A custom command is a named interaction that expands into a familiar request or workflow when a person explicitly selects it. Commands remain useful as simple entry points, while Skills better suit reusable work that needs its own guidance, resources, and controlled sequence. A well-designed Skill names its trigger, required inputs, intended output, permitted tools, and conditions for stopping or reporting uncertainty.

A trigger is the situation that makes the Skill relevant, such as a request to review the security impact of a proposed code change. An argument is a value supplied by the caller, and a hint briefly explains what value belongs there so explicit invocation is less error-prone. Supporting files might hold an approved review rubric, meaning the criteria used to decide which issues deserve a finding. A tool allowlist names the functions a workflow may call, applying least privilege, which means granting only the capabilities needed for its purpose. Fictional Harbour Resolution might package a secure pull-request review Skill that reads changed files, loads its rubric, runs approved tests, and returns a fixed set of finding fields.

A pull request is a proposed set of repository changes submitted for review, and its diff is the record of lines added, removed, or modified. Someone using this hypothetical Skill would see each candidate issue tied to a changed file, an explanation, supporting code, and an allowed severity level. The tempting shortcut would be to give the review Skill every tool available because broader access feels more convenient. A better design might allow file reading, text search, diff inspection, and named test commands while excluding deployment and production-database access. An allowlist that is too narrow can prevent a legitimate check, so the workflow should report missing capability clearly instead of inventing a result or silently broadening access.

A forked session is a separate continuation copied from existing context, and a subagent is a specialised worker given a bounded part of the task. Either technique can isolate a focused review from unrelated conversation, although isolation does not repair excessive permissions or prevent every shared-system conflict. A small custom command may still be the clearest option when all the team needs is a memorable way to launch one bounded prompt. Plan mode is a working style in which Claude inspects the problem and proposes an approach before immediately making the full set of changes. Consider a hypothetical engineer asked to replace an authentication library used by several services, tests, and deployment files.

Text description

• Plan mode: Inspect affected areas, dependencies, execution order, tests, and unresolved decisions before making the full change.
• Direct execution: Fits a clear, bounded change whose potential blast radius is small.

In plan mode, that person could first see which areas are affected, which components rely on the old library, the safe order for replacing it, the expected tests, and the decisions still unresolved. The tempting mistake would be to start editing the first matching file before discovering that another service relies on the old behavior. Reviewing the plan can expose a missed dependency or an unsafe assumption while correction is still cheap. Direct execution is usually a better fit for a bounded change with clear acceptance conditions and a small blast radius, meaning a limited amount of code or operation can be affected. The practical choice depends on whether the cost of a wrong implementation justifies an explicit plan review.

Planning every trivial edit adds delay and ceremony without necessarily improving the result. Plan mode also does not grant safety by itself, because tool permissions and external controls still decide which actions can execute. Claude Code workflows may read files, write files, make targeted edits, search text, match file patterns, and invoke shell commands. A shell is the command-line environment used to run programs, so unrestricted shell access can reach far beyond the test command a workflow actually needs. A codebase-orientation workflow may need reading, search, and file matching but no write access at all. A test-fixing workflow may need targeted edits and permission to run a constrained test command rather than arbitrary programs.

Text description

• Reproduce the failure: Confirm that an imported name containing an apostrophe triggers the reported problem.
• Add a failing test: Capture the reported valid input in the existing test area.
• Implement the fix: Make the smallest adequate change without unrelated cleanup.
• Rerun focused tests: Use actual results as evidence that the behavior now meets the acceptance condition.

Deployment generally deserves a separately governed workflow because it can change shared environments and affect people beyond the coding session. A reliable change prompt states the goal, constraints, relevant locations, expected evidence, and acceptance tests. An acceptance test is an observable check that defines what must work for the change to count as successful. Concrete examples of accepted code patterns are often more informative than broad requests to make code clean, elegant, or secure. In a hypothetical support-tool bug, an engineer might report that names containing an apostrophe fail during import and identify the code that reads imported data and the existing test directory. Claude could then reproduce the failure, explain the likely cause, add a test that fails for the reported input, implement the smallest adequate fix, and rerun the focused tests.

Evidence is something directly observed, such as a failing test or a cited line of code, while inference is a conclusion drawn from that evidence. The proposed cause remains an inference, while observed code behavior and test results provide evidence that can support or weaken it. Real command output gives the engineer stronger grounds for judging the change than a confident statement that the tests should pass. The smallest adequate fix does not mean the fewest characters at any cost, because a slightly broader change may be necessary to preserve a clear interface or handle the full valid input class. Unrequested cleanup creates scope creep, which is work expanding beyond the agreed goal and making review harder.

A session is the continuing conversation and working context for a task, allowing investigation and refinement to carry across multiple turns. Resuming a session preserves useful history, but the engineer should recheck assumptions if the repository or external environment has changed since the earlier work. Forking a session lets two approaches start from the same background without mixing their subsequent reasoning. In a hypothetical performance fix, one fork might explore combining several database requests into one operation while another examines reusing previously calculated results, with neither experiment automatically becoming the accepted solution. A branch is an independent line of version-controlled changes, and a worktree is a separate checked-out directory that can place another branch alongside the first.

Parallel coding sessions should use isolated branches or worktrees so their file edits do not overwrite one another. That isolation has limits because sessions can still interfere by sharing test services or login secrets, creating the same external items, or later making incompatible changes to the same code. Continuous integration, or CI, is an automated process that checks proposed changes in a controlled environment, and its pipeline is the ordered set of automated jobs that performs those checks. Programmatic print mode lets a CI job send a bounded request to Claude Code and receive a result without conducting an interactive conversation. A dependable job fixes the working directory, controls configuration, declares permissions, and supplies only the inputs intended for that run.

A service account is a non-human account used by an automated job or service. The job's service account should be distinctly authenticated and narrowly authorized, because knowing which account ran the review does not justify granting it merge or deployment power. Machine-readable JSON is a structured text format that lets later pipeline steps read named fields instead of scraping flexible prose. A JSON schema defines the permitted structure, required fields, and value shapes of that output. A basic JSON check confirms that the text follows JSON syntax, while JSON Schema validation checks its structure, required fields, and value types; neither establishes that a finding is true.

Text description

• JSON syntax: Checks whether the output is valid JSON text.
• Schema validation: Checks required fields, permitted structure, and value types.
• Semantic validation: Checks whether cited evidence exists and the finding applies to the proposed change.

Semantic validation examines what the fields mean and whether the claimed finding is supported by the actual change. Suppose a hypothetical CI reviewer reports a high-severity authorization flaw in a file that the pull request never touches. The output might satisfy every schema rule while failing semantic checks because the cited file, relevant line, and relationship to the submitted diff are missing. A developer would see an impressively structured comment, and the tempting response would be to trust it because the formatting looks official. The better pipeline verifies that cited files and lines exist, severity values are permitted, explanations are present, and findings apply to the proposed change.

Text description

• Too little context: Can hide the sequence of calls leading to an important operation.
• Focused context: The diff plus enough surrounding code can strengthen relevance.
• Too much context: Can distract the review, raise processing cost, and encourage unrelated findings.

A false positive is a reported problem that is not actually present, while a false negative is a real problem the review fails to report. Precise review criteria and examples of both reportable and non-reportable cases can reduce ambiguity, though they cannot eliminate either kind of error. Giving the reviewer the diff plus enough surrounding code often provides stronger relevance than handing it the entire repository without focus. Too little context can hide the sequence of function calls leading to an important operation, while too much can distract the review, increase processing cost, and encourage findings unrelated to the change. The workflow should permit a clean result with no findings so the model is not pressured to manufacture an issue merely to fill an output field.

Each finding should identify concrete evidence and keep any inferred consequence clearly tied to that evidence. An independent second pass can challenge candidate findings, verify citations, and reject items that the first reasoning path cannot support. That second pass provides confirmation, not authorized approval, because approval belongs to the designated person or policy-controlled system empowered to accept the change. Two passes can share the same blind spot, especially when they receive the same incomplete context or rubric. An automated Claude review should not become the sole merge gate unless the organisation has deliberately validated that role and accepted its failure modes. Deterministic tests are checks that apply predefined rules and should produce the same result from the same relevant inputs, making them valuable alongside model judgment.

Required human review may also remain appropriate where business context, accountability, or unusual risk cannot be captured reliably by automated checks. A high-severity automated finding can route the change to an authorized reviewer instead of silently blocking every developer or approving the work on its own. A hook is a configured action that runs at a particular stage of the Claude Code workflow to inspect, block, or automate behavior. A pre-tool hook runs before a tool action and can reject a dangerous command or require identifying information about the action, such as its target environment or approval reference. In a hypothetical change to a database’s structure, an engineer might see a clear block message because the proposed command targets an unapproved environment.

Text description

• Requested tool action: The workflow proposes a command, edit, or other tool operation.
• Pre-tool hook: Inspects the action before execution and can reject a dangerous command or missing approval information.
• Execute permitted action: The permitted command, edit, or other tool operation runs.
• Post-edit hook — edits only: When the action changed a file, this hook can format the result or launch a focused check.
• Completion hook: Before work is treated as finished, it can require configured tests or trusted results and block completion when they fail or are absent.

The tempting reaction is to remove the hook, while the better response is to correct the target or use the separately authorized release process. This protection can slow legitimate emergency work, so any exception process needs an explicit owner and a record showing who used it and why, rather than an invisible bypass. A post-edit hook runs after a file change and can apply formatting or launch a focused check while the edit is still easy to correct. A completion hook runs when work is about to be treated as finished and can run the configured tests or validate trusted execution results, blocking completion when those checks fail or their results are absent.

That hook provides evidence only for the checks configured to run there, so it cannot establish that every relevant property of the change is correct. Hooks should log what ran, why it passed or failed, and what the engineer can do next, because invisible failures make controlled behavior look arbitrary. Failing closed means an uncertain hook blocks progress, while failing open means it permits progress and records or warns about the failure. Failing closed protects the boundary more strongly but can halt work when a required service fails intermittently, whereas failing open keeps work moving but may allow the very action the hook was meant to stop.

Local hooks also protect only the paths where they actually run, so critical policy often needs reinforcement in CI, protected branches, access controls, and the service receiving the operation. The durable design is to keep guidance concise, give each workflow minimum sufficient capability, demand evidence for machine findings, and place hard boundaries in systems that can enforce them. Prompts shape behavior, schemas constrain output structure, reviewers assess evidence, and authorized controls decide what may proceed. Claude Code becomes a more trustworthy engineering partner when every layer has a clear job and its limitations remain visible.