Claude Code Tutorial: Headless Mode and Compliance Hooks

This claude code tutorial works through the patterns that recur in real developer pipelines and in CCDV-F exam questions: running Claude Code in headless (non-interactive) mode, configuring hooks for compliance logging, and setting correct agent termination conditions. These topics span Domain 3 (Claude Code, 3.1% of the 53-item exam), Domain 1 (Agents and Workflows, 14.7%), and Domain 2 (Applications and Integration, 33.1%), so mastery pays off across multiple sections of the score report.

What does the CCDV-F exam test about Claude Code?

The Claude Certified Developer, Foundations exam (code: CCDV-F, $125 per attempt) covers Claude Code under Domain 3 at a weight of 3.1%. That is roughly one to two of the 53 items. However, Claude Code patterns also surface in Domain 1 (Agents and Workflows) and Domain 2 (Applications and Integration), because exam writers frame headless invocation and hook design as integration and workflow decisions rather than as pure IDE tooling.

The practical implication: treat Claude Code knowledge as cross-domain. A scenario might describe a CI pipeline that needs to block unauthorised file writes from an agent while maintaining an audit log of every attempt, including blocked ones. That is a hooks question dressed as an integration scenario. Understanding the tool's configuration model, not just its interactive surface, is what earns credit.

What is the difference between headless mode and interactive mode?

Interactive mode is the default. You open a terminal, run claude, and hold a back-and-forth conversation. Claude Code reads your input, runs tools, and returns results in real time. The session persists until you close it.

Headless mode uses the -p flag. You pass a prompt string on the command line, Claude Code executes the task, and exits. No human input is expected or possible during the run. This is the correct choice for CI pipelines, scheduled jobs, and orchestrators that call Claude Code programmatically.

# Interactive: open a session
claude

# Headless: single prompt, exits after completion
claude -p "Run the test suite and write a JSON summary to test-results.json"

# Headless with explicit output format
claude -p "Audit all Python files for unused imports" --output-format json

The CCDV-F exam distinguishes these modes by the context a scenario provides. If the scenario mentions a CI job, a cron task, or an orchestrator, headless is the expected answer. If it mentions a developer iterating on a feature branch, interactive is appropriate.

How do you configure hooks for compliance logging in Claude Code?

Hooks are shell commands registered in Claude Code configuration that fire at specific lifecycle events. The four hook points are PreToolUse, PostToolUse, PreCompact, and Stop. For compliance logging and policy enforcement on file writes, PreToolUse is the control point; PostToolUse captures what actually executed.

The three-level configuration hierarchy governs which hooks apply. User-level settings (~/.claude/settings.json) apply across all projects. Project-level settings (.claude/settings.json) apply only to that repository and are typically committed to version control. Local project settings (.claude/settings.local.json) override project-level settings but are not committed, making them appropriate for developer-specific overrides.

A common exam scenario asks how to log every file-write attempt, including those that a policy hook subsequently blocks. The answer requires registering two hooks in sequence under the same event: a logging hook that runs unconditionally, followed by a policy check hook that can exit non-zero to block the write.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash /scripts/log-write-attempt.sh"
          },
          {
            "type": "command",
            "command": "bash /scripts/policy-check.sh"
          }
        ]
      }
    ]
  }
}

Hook ordering is deterministic and consequential. Claude Code runs hooks in array order and stops processing the list on the first non-zero exit. Place the logging hook first so it always writes to the audit log, regardless of what the policy check returns. If the policy check runs first and exits non-zero, Claude Code will not invoke subsequent hooks, and blocked attempts will go unlogged.

The hooks vs prompts decision framework states the underlying principle: use hooks when enforcement must be deterministic and unconditional; use prompt instructions when you want flexible, context-sensitive guidance. Compliance logging is always a hook task, not a prompt task.

How does CLAUDE.md shape Claude Code behaviour within a project?

CLAUDE.md is a plain markdown file that Claude Code reads at the start of every session, interactive and headless alike. It is the primary mechanism for encoding project-specific conventions, constraints, and context without relying on runtime system prompt injection.

A well-designed CLAUDE.md covers three categories: project structure (which directories hold what), coding conventions (naming patterns, preferred libraries, style rules), and operational constraints (which files must not be modified, which tests must pass before any commit).

# Project conventions

## Structure
- Source code lives in `src/`; tests mirror the source tree under `tests/`
- Generated files live in `dist/` and must never be edited directly

## Code style
- Python: Black formatting, type hints on all public functions
- No print statements in production code; use the `logging` module

## Constraints
- Never modify `src/auth/` without an explicit instruction from the team lead
- All tests in `tests/integration/` must pass before any file commit

The version control implications of this choice matter in team settings. CLAUDE.md is typically committed to the repository so that all developers and CI pipelines share the same baseline conventions. The .claude/settings.local.json file, by contrast, is gitignored, making it appropriate for developer-specific overrides that should not affect teammates or automated runs.

CCDV-F scenarios that mention project-wide convention enforcement are almost always pointing at CLAUDE.md as the correct tool. Scenarios that mention individual developer overrides point at local settings. The distinction is predictable once the configuration hierarchy is clear.

How does prompt injection defence apply to file and shell operations?

When Claude Code has access to tools that read files, write files, and execute shell commands, a successful prompt injection can have a large blast radius. An adversarial string embedded in a file Claude Code reads during a task could instruct it to modify unrelated files or exfiltrate data.

The exam tests two mitigation layers.

Tool call interception via hooks acts as a programmatic gate before any tool executes. A PreToolUse hook on the Bash tool can reject shell commands that reference paths outside the project directory or that attempt network calls.

#!/bin/bash
# Reject shell commands that touch /etc or use curl/wget
if echo "$CLAUDE_TOOL_INPUT" | grep -qE '(/etc/|curl |wget )'; then
  echo "Blocked: policy violation" >&2
  exit 1
fi
exit 0

Scope constraints in configuration reduce the available surface before hooks are needed. A project-level configuration that restricts write access to the project root removes the risk of out-of-scope writes even if a hook fails to fire.

Tool call interception hooks appear in exam scenarios where the requirement is unconditional. The correct answer is always a hook, not a system prompt instruction, because a sufficiently crafted injection can override a prompt instruction but cannot override a process exit code.

What are correct agent termination conditions in a Claude Code pipeline?

Agent termination is a Domain 1 topic that surfaces regularly in Claude Code scenarios because Claude Code runs its own agentic loop. The exam distinguishes task-complete stops from error stops.

The primary stop condition for an agent loop is task completion signalled by the model (stop_reason: "end_turn"). Secondary stops include tool errors that exceed a configured retry threshold and explicit human-in-the-loop interrupts configured by the operator.

Anti-patterns the exam probes:

• Stopping on the first tool error without retry: too aggressive, masks recoverable failures
• Never stopping on tool errors: no blast-radius limit, the loop runs indefinitely
• Using elapsed time as the primary stop condition: ignores task state, produces non-deterministic behaviour

The compliance hook scenario application concept covers how Stop hooks flush final audit entries when the loop terminates, whether by success or by an error threshold being reached.

How does Domain 2 (Applications and Integration) frame Claude Code decisions?

Domain 2 is the largest domain on the CCDV-F exam at 33.1% of the 53 items. It tests integration decisions: when to call Claude via the Messages API directly versus when to use Claude Code as the integration layer.

The practical heuristic is scope. Claude Code is an opinionated wrapper designed for file-system and shell-centric tasks inside a project repository. For general-purpose API integration, a direct Messages API call with defined tool schemas is more appropriate. For tasks that involve reading and editing source files, running a test suite, and operating within a repository, Claude Code adds value through its built-in tool set, hook system, and configuration model.

The exam does not require deep knowledge of Claude Code's internals. It expects you to identify when headless mode is appropriate, explain how hooks interact with tool execution, and select the correct configuration scope for a given organisational requirement. That is the practical integration judgement the CCDV-F validates.

Where can you practise these CCDV-F skills?

AI Skill Certs offers adaptive study and practice exams for the CCDV-F exam, scored on the same 100-to-1000 scale with 720 as the passing threshold, matching the real 53-item format. The adaptive engine uses Bayesian Knowledge Tracing with a 0.90 mastery threshold, routing you back to concepts like hook ordering and headless mode until you have demonstrably mastered them. Archie, the platform's Socratic tutor, guides you through hook configuration scenarios with graduated hints rather than giving away answers.

AI Skill Certs is independent and is not affiliated with or approved by Anthropic.