Claude Code Enforcement

Integrating Claude Code with the consistency framework

This page explains how Claude Code works with the Project Consistency Framework to automatically enforce standards.

How Claude Uses the Framework

Claude Code reads your project’s consistency files and uses them to:

  1. Reference correct values — Uses globals.yml instead of hardcoding
  2. Validate changes — Checks that code matches claims
  3. Catch drift — Warns when changes might cause inconsistencies
  4. Document properly — Updates provenance and claims as needed

Files Claude Reads

File Purpose How Claude Uses It
config/globals.yml Parameter values References for all constants
config/consistency_registry.yml Claim tracking Validates manuscript claims
R/globals_loader.R Config loading utilities Ensures code uses loader
docs/DATA_PROVENANCE.md Data sources Documents data origins
docs/plans/*.md Design decisions Understands project rationale
DEFAULTS.md Parameter documentation Understands parameter choices

Generating Consistency Files with Claude

Claude can help you create all the files needed for the consistency framework. Here are specific prompts for each file:

Initial Setup

To set up the entire framework at once:

> Set up the project consistency framework for my simulation study.
> My key parameters are: n_reps (1000 for testing, 10000 for production),
> alpha = 0.05, and power_target = 0.80.

Claude will create all required files in the correct directory structure.

Individual File Generation

config/globals.yml

> Create config/globals.yml for my project with these parameters:
> - simulation: n_reps_low (500), n_reps_high (10000)
> - analysis: alpha (0.05), power_target (0.80)
> - project seed: 2024

config/consistency_registry.yml

> Create config/consistency_registry.yml to track these claims:
> - Manuscript states "10,000 Monte Carlo replications"
> - Methods section claims "5% significance level"
> Add the locations where these appear in manuscript/paper.qmd

R/globals_loader.R

> Create R/globals_loader.R with load_globals() function that:
> - Reads config/globals.yml
> - Returns a list with all parameters
> - Handles missing file gracefully

scripts/validate_consistency.R

> Create scripts/validate_consistency.R that:
> - Loads globals.yml and consistency_registry.yml
> - Checks that all claims match their expected values
> - Scans R/ files for hardcoded values that should use globals
> - Reports any inconsistencies found

DEFAULTS.md

> Create DEFAULTS.md documenting all parameters in globals.yml
> Include: parameter name, value, justification, and where it's used

docs/DATA_PROVENANCE.md

> Create docs/DATA_PROVENANCE.md for my project with:
> - Figure 1: simulation results from results/sim_summary.csv
> - Table 1: operating characteristics from results/oc_table.csv
> Include the generating scripts and targets targets

Integration File Updates

Update _targets.R

> Update _targets.R to use the globals loader:
> - Source R/globals_loader.R at the top
> - Replace hardcoded values with cfg$parameter$name
> - Add config as a target dependency

Create .github/workflows/validate.yml

> Create a GitHub Actions workflow that runs validate_consistency.R
> on every push and pull request

Update Makefile

> Add a validate-consistency target to the Makefile that runs
> the validation script before the submit target

Updating Existing Files

When your project parameters change:

> Update globals.yml: change n_reps_high from 10000 to 20000
> Also update the consistency registry claim to match

Claude will:

  1. Update config/globals.yml
  2. Update config/consistency_registry.yml
  3. Note any manuscript sections that need re-rendering
  4. Optionally run validation to confirm consistency

Automatic Behaviors

When Writing Code

Claude automatically:

> Add a simulation with 1000 iterations

Claude reads globals.yml and generates:
  n_reps <- globals$simulation$n_iterations

NOT:
  n_reps <- 1000  # Hardcoded - wrong!

When Reviewing Code

The /review skill checks:

  • Are hardcoded values present that should use globals.yml?
  • Do parameter names match canonical names?
  • Are consistency registry claims still valid?

When Updating Manuscripts

Claude uses dynamic values:

> Update the methods section with the sample size

Claude generates:
  The study used `r params$n` participants.

NOT:
  The study used 500 participants.

The /validate Skill

Run validation checks on demand:

> /validate

This skill:

  1. Loads config/globals.yml
  2. Scans R/ for hardcoded values
  3. Checks manuscript for hardcoded numbers
  4. Verifies consistency_registry.yml claims
  5. Reports any inconsistencies

Example Output

Validation Results:
------------------

✓ globals.yml is valid YAML
✓ All R files use config loader

⚠ Potential issues:
  - R/simulation.R:42 contains hardcoded value: n_reps = 1000
    → Should use: globals$simulation$n_iterations

  - manuscript/paper.qmd:127 contains hardcoded: "500 participants"
    → Should use: inline R expression

✗ Consistency registry violations:
  - Claim sim_reps: Expected 10000, found 1000 in R/simulation.R

Hook Integration

Pre-Commit Validation

Add to .claude/settings.json:

{
  "hooks": {
    "pre-commit": {
      "command": "Rscript scripts/validate_pipeline_consistency.R"
    }
  }
}

This blocks commits that would introduce inconsistencies.

Session Review

{
  "hooks": {
    "session-stop": {
      "agent": "lab-reviewer"
    }
  }
}

Reviews all session changes for consistency issues.

Review Checklist Integration

Create .claude/review-checklist.yml with consistency patterns:

patterns:
  # Hardcoded values
  - name: "Hardcoded n_reps"
    regex: "n_reps\\s*=\\s*\\d+"
    severity: critical
    message: "Use globals$simulation$n_reps instead"

  - name: "Hardcoded alpha"
    regex: "alpha\\s*=\\s*0\\.\\d+"
    severity: critical
    message: "Use globals$analysis$alpha instead"

  # Naming conventions
  - name: "Wrong parameter name"
    regex: "\\bnmax\\b"
    severity: warning
    message: "Use total_n instead of nmax"

  - name: "Wrong alpha name"
    regex: "\\btype_1_error\\b"
    severity: warning
    message: "Use type1 instead of type_1_error"

file_triggers:
  critical:
    - "config/globals.yml"
    - "config/consistency_registry.yml"
  warning:
    - "manuscript/*.qmd"

Workflows

Making Config Changes

> I need to change n_iterations from 1000 to 2000

Claude:
1. Updates config/globals.yml
2. Finds all references in R/
3. Verifies no hardcoded values
4. Updates consistency_registry.yml if needed
5. Notes manuscript may need re-rendering

Adding New Parameters

> Add a new parameter for bootstrap_samples

Claude:
1. Adds to globals.yml
2. Creates loader access
3. Updates DEFAULTS.md documentation
4. Adds to consistency registry

Checking Before Submission

> Run pre-submission checks

Claude:
1. Runs /validate
2. Checks all claims in registry
3. Verifies data provenance
4. Confirms figures match outputs
5. Reports ready or lists issues

Common Prompts

Task Prompt
Check consistency “/validate”
Find hardcoded values “Are there any hardcoded values in R/?”
Update config “Change n_iterations to 2000 in globals.yml”
Check claims “Verify all consistency registry claims”
Document data “Update DATA_PROVENANCE.md with the new dataset”
Review changes “/review”

Best Practices

Reference globals.yml explicitly

> Use globals$simulation$n_reps for the iteration count

Ask Claude to check before committing

> Before I commit, check for any consistency issues

Document data sources immediately

> Add this dataset to DATA_PROVENANCE.md

Update registry when adding claims

> Add a new claim to the registry for this method description

Data Provenance Tracking

Claude Code can help maintain docs/DATA_PROVENANCE.md as your project evolves. This is particularly valuable because data sources, processing steps, and figure generation often change during development.

Automatic Provenance Updates

When you add or modify outputs, ask Claude to update provenance:

> I just added Figure 3 showing the sensitivity analysis.
> Update DATA_PROVENANCE.md with:
> - Data source: results/sensitivity_analysis.csv
> - Script: scripts/generate_figures.R
> - Target: fig3_sensitivity

Claude will:

  1. Add the new entry to docs/DATA_PROVENANCE.md
  2. Verify the referenced files exist
  3. Check the targets pipeline includes the target
  4. Warn if any referenced files are missing

Provenance Audits

Before submission, ask Claude to audit your provenance:

> Audit DATA_PROVENANCE.md - check that all referenced files exist
> and all figures/tables in the manuscript are documented

Claude will:

  1. Parse the provenance document
  2. Verify each data source file exists
  3. Verify each output file exists
  4. Check file modification timestamps (outputs should be newer than inputs)
  5. Scan the manuscript for figures/tables not in provenance
  6. Report any gaps or inconsistencies

Regeneration Assistance

When data sources change:

> The raw data in data/clinical_outcomes.csv was updated.
> What outputs need to be regenerated?

Claude traces the dependency chain through DATA_PROVENANCE.md and the targets pipeline to identify affected outputs.

Centralized Configuration

Claude enforces the “single source of truth” principle by always referencing config/globals.yml rather than using hardcoded values.

Why Centralization Matters

Without centralization:

# File 1: simulation.R
n_reps <- 10000

# File 2: analysis.R
n_reps <- 1000  # Oops, different value!

# Manuscript: paper.qmd
"We used 10,000 replications"  # Which is correct?

With centralization:

# All files reference the same source
cfg <- load_globals()
n_reps <- cfg$simulation$n_reps_high  # Always consistent

Claude’s Centralization Behaviors

When writing new code, Claude automatically:

  • Checks if a value exists in globals.yml
  • Uses the config loader to access it
  • Suggests adding new parameters to globals.yml if needed

When reviewing code, Claude flags:

  • Hardcoded numeric values that should be centralized
  • Inconsistent parameter names across files
  • Values that don’t match globals.yml

When updating parameters, Claude:

  • Modifies globals.yml (single location)
  • Finds all code references to verify they use the loader
  • Updates consistency_registry.yml if the parameter has manuscript claims
  • Notes which outputs may need regeneration

Centralization Prompts

Task Prompt
Centralize existing value “Move this hardcoded n_reps=1000 to globals.yml”
Add new parameter “Add a new parameter batch_size=64 to globals.yml”
Find all references “Where is simulation.n_reps used in the codebase?”
Audit centralization “Are there any hardcoded values that should be in globals.yml?”

Template Status

WarningTemplates Reference But Don’t Include Framework Files

The lab templates (template-research-project, template-methods-paper, template-clinical-trial) reference the consistency framework in their CLAUDE.md files but do not yet include the actual files. When starting a new project from a template, ask Claude to generate them.

What Templates Include

File research-project methods-paper clinical-trial
config/globals.yml ❌ ❌ ❌
R/globals_loader.R ❌ ✅ (symlink) ✅ (symlink)
_targets.R ❌ ✅ ✅
docs/DATA_PROVENANCE.md ❌ ❌ ❌
DEFAULTS.md ❌ ❌ ❌
scripts/validate_consistency.R ❌ ❌ ❌
.claude/CLAUDE.md ✅ ✅ ✅

Setting Up After Cloning a Template

When you clone a template for a new project, ask Claude to set up the missing framework files:

> I just cloned template-methods-paper for my new project.
> Set up the consistency framework with:
> - Simulation parameters: n_reps (500 testing, 10000 production)
> - Analysis parameters: alpha=0.05, power_target=0.80
> - Project seed: 2024

Claude will:

  1. Create config/globals.yml with your parameters
  2. Create config/consistency_registry.yml (empty, ready for claims)
  3. Create docs/DATA_PROVENANCE.md template
  4. Create DEFAULTS.md documenting your parameters
  5. Create scripts/validate_consistency.R
  6. Update _targets.R to use the globals loader (if not already)

Reference Implementation

For a complete example of the consistency framework in action, see:

~/Downloads/adaptive-trial-bo-paper/
├── globals.yml                              # Centralized parameters
├── scripts/validate_pipeline_consistency.R  # Validation script
└── docs/plans/                              # Design documentation

Troubleshooting

“Claude uses hardcoded values”

Check that globals.yml exists and is valid:

cat config/globals.yml

Remind Claude:

> Use values from globals.yml, never hardcode numbers

“Validation keeps failing”

Run validation manually to see details:

Rscript scripts/validate_pipeline_consistency.R

“Claims don’t match”

Check the registry:

cat config/consistency_registry.yml

Ask Claude to update:

> Update the consistency registry to match current values

See Also