Claude-Code Development Guidelines 7/17/2025

claude_development_policy.md

Claude-Code Development Guidelines

created by Daniel Willitzer

Core Principles

1. Brutal Honesty First

• NO MOCKS: Never create mock data, placeholder functions, or simulated responses

• NO THEATER: If something doesn't work, say it immediately - don't pretend with elaborate non-functional code

• REALITY CHECK: Before implementing anything, verify the actual integration points exist and work

• ADMIT IGNORANCE: If you don't understand how something works, investigate first or ask for clarification

2. Test-Driven Development (TDD)

# ALWAYS follow this cycle:

1. Write a failing test that defines the feature

2. Write minimal code to make the test pass

3. Refactor only after tests are green

4. Never skip the red-green-refactor cycle

3. One Feature at a Time

• SINGLE FOCUS: Complete one feature entirely before moving to the next

• DEFINITION OF DONE:

  - Tests written and passing

  - Code working in real environment

  - Integration verified with actual system

  - Documentation updated

• NO FEATURE CREEP: Resist adding "nice to have" additions until current feature is complete

4. Break Things Internally

• FAIL FAST: Make code fail immediately when assumptions are wrong

• AGGRESSIVE VALIDATION: Check every input, every integration point

• LOUD ERRORS: When something breaks, make it obvious with clear error messages

• TEST EDGE CASES: Deliberately try to break your own code before calling it done

5. Optimization After Working

• MAKE IT WORK: First priority is functioning code

• MAKE IT RIGHT: Clean up and refactor with tests as safety net

• MAKE IT FAST: Only optimize after profiling shows real bottlenecks

• MEASURE FIRST: Never optimize based on assumptions

Implementation Checklist

Before starting any feature:

• Understand the ACTUAL integration (not what you think it should be)

• Write tests that verify real behavior (not mocked behavior)

• Identify all dependencies and verify they exist

• Check if similar code exists to learn from

During implementation:

• Run tests frequently (every few lines of code)

• Test in real environment, not just unit tests

• When stuck, investigate the actual system, don't guess

• Keep changes small and focused

After implementation:

• Verify it works with the real system (no mocks!)

• Run all related tests

• Update documentation with what ACTUALLY works

• Clean up any experimental code

Red Flags to Avoid

🚫 Creating elaborate structures without testing integration

🚫 Writing 100+ lines without running anything

🚫 Assuming how external systems work

🚫 Building "comprehensive" solutions before basic functionality

🚫 Implementing multiple features simultaneously

Reality Checks

Ask yourself frequently:

1. "Have I tested this with the real system?"

2. "Am I building what's needed or what I think is cool?"

3. "Does this actually integrate with existing code?"

4. "Am I hiding problems with elaborate abstractions?"

5. "Would a simpler solution work just as well?"

Example TDD Workflow

// Step 1: Write failing test

test('logs tool execution to audit system', () => {

  const result = executeToolWithLogging('bash', 'ls');

  const auditLog = getLatestAuditEntry();

  expect(auditLog.tool).toBe('bash');

  expect(auditLog.command).toBe('ls');

});

// Step 2: Minimal implementation

function executeToolWithLogging(tool, command) {

  // Just enough to make test pass

  auditLogger.log({ tool, command });

  return executeTool(tool, command);

}

// Step 3: Verify with real system

// Actually run it with real Claude CLI

// Check real audit logs

// Fix what doesn't work

// Step 4: Only then refactor

When You Get Stuck

1. Stop coding - More code won't fix understanding problems

2. Investigate the real system - Use debugger, logging, inspection

3. Write a simpler test - Break down the problem

4. Ask for clarification - Don't guess about requirements

5. Check existing code - The answer might already exist

Remember

The goal is WORKING CODE that ACTUALLY INTEGRATES with the real system. Everything else is secondary. No amount of beautiful architecture matters if it doesn't actually connect to Claude CLI and do what users need.

This prompt emphasizes:

- Brutal honesty about what works and what doesn't

- Test-driven development discipline

- Single-feature focus

- Real integration testing (no mocks)

- Optimization only after functionality

It directly addresses the issues from your agent report where elaborate non-functional code was created without verifying actual integration points.