Skip to content

docs: restructure CLAUDE.md to consolidate team rules #376

@mcj-coder

Description

@mcj-coder

Summary

Restructure CLAUDE.md and CLAUDE.local.md to properly separate concerns:

  • CLAUDE.md (committed): All team/repo rules and process enforcement
  • CLAUDE.local.md (gitignored): Machine-specific configuration only

Background

During a session continuation, process violations occurred because:

  1. Session summary was treated as authoritative without re-initializing
  2. Skills-first workflow was not loaded
  3. TDD/BDD was skipped for documentation changes
  4. Issues were not read before implementing

The existing CLAUDE.md was too brief and CLAUDE.local.md contained team rules that should be shared.

Changes

CLAUDE.md additions:

  • EXTREMELY-IMPORTANT skill invocation block at top
  • Comprehensive session initialization protocol
  • TDD/BDD enforcement details with examples
  • Complete "Using Skills" guidance with flow diagram
  • Skill rationalizations table (red flags)
  • Persona-switching PR workflow (two-account pattern)
  • Session continuation protocol
  • Compliance checklists (before implementation/PR/merge)
  • Evidence requirements summary

CLAUDE.local.md reduced to:

  • Persona script path
  • Account mappings (contributor/maintainer)
  • Session start commands
  • Troubleshooting

Acceptance Criteria

  • CLAUDE.md contains all team/repo process rules
  • CLAUDE.local.md contains only machine-specific config
  • .gitignore updated to exclude CLAUDE.local.md
  • Both files pass linting

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions