Claude Code build logging setup - run once per machine

setup-build-log.sh

#!/bin/bash
# Claude Code build logging — one command setup.
# curl -sL https://gist.githubusercontent.com/chilledpear/0bbc9bdf02332a691c8726d55b54f375/raw/setup-build-log.sh | bash

set -e

# 1. Global: ~/.claude/CLAUDE.md (instructions every session reads)
mkdir -p ~/.claude
cat > ~/.claude/CLAUDE.md << 'GLOBALEOF'
# Global Instructions

## Engineering Log (MANDATORY)

Every project should maintain build logs. If `BUILD_STATE.md` exists in the project root, this project uses the logging system. Follow these rules:

### If BUILD_STATE.md exists in the project root:

**On session start:**
- READ `BUILD_STATE.md` first for quick context
- Only read `BUILD_LOG.md` if you need historical detail about a specific past decision

**During the session — after each significant change:**

A "significant change" is: file created/deleted/edited, design decision made, bug found/fixed, feature completed.

APPEND to `BUILD_LOG.md`:
```
---
### [DATE] [Brief description of what just happened]
- Files changed: [list]
- Why: [reasoning]
- State after: [what works/what's broken]
```

REWRITE `BUILD_STATE.md` with current project state. Keep under 150 lines:
```
# Project State (last updated [DATE])

## Architecture
- How the system is structured, key files and their roles

## What works
- Features/components that are functional

## What's broken or incomplete
- Known issues, unfinished work

## Recent changes (last 3-5 sessions)
- Brief summary of recent work

## Active decisions
- Design choices that are still relevant and WHY
- Remove decisions that are no longer relevant
```

**At session end** (if user says "done" / "wrap up"), also append a session summary to `BUILD_LOG.md`:
```
---
## [DATE] Session Summary: [Title]

### What was done this session
- Full bullet list of all changes

### Key decisions
- Decisions and WHY

### Next steps
- What the next session should pick up
```

### If BUILD_STATE.md does NOT exist:
- Do not create log files automatically
- If the project seems non-trivial, suggest the user run `init-build-log` to set up logging

### Rules
- BUILD_LOG.md: APPEND only. Never overwrite previous entries.
- BUILD_STATE.md: REWRITE each session. Keep current and compact.
- Be specific: name files, functions, and line numbers.
- If nothing was changed (research-only session), still log what was learned.
- Writing logs is as important as writing code. Do not skip it.
GLOBALEOF
echo "✓ ~/.claude/CLAUDE.md"

# 2. Shell function: init-build-log (for future projects)
SHELL_RC=""
if [ -f ~/.zshrc ]; then
  SHELL_RC=~/.zshrc
elif [ -f ~/.bashrc ]; then
  SHELL_RC=~/.bashrc
else
  SHELL_RC=~/.zshrc
  touch "$SHELL_RC"
fi

if grep -q "init-build-log" "$SHELL_RC" 2>/dev/null; then
  echo "✓ init-build-log already in $SHELL_RC"
else
  cat >> "$SHELL_RC" << 'RCEOF'

# Initialize Claude Code build logging in current project
init-build-log() {
  if [ -f "BUILD_STATE.md" ]; then
    echo "Build log already exists in this directory."
    return 0
  fi
  cat > BUILD_STATE.md << 'EOF'
# Project State (last updated)

## Architecture
- Not yet documented

## What works
- Not yet catalogued

## What's broken or incomplete
- Not yet catalogued

## Recent changes
- Initial setup

## Active decisions
- None yet
EOF
  cat > BUILD_LOG.md << 'EOF'
# Build Log

Chronological record of every Claude Code session and what was built, changed, or decided.

EOF
  echo "✓ Build logging initialized"
}
RCEOF
  echo "✓ init-build-log added to $SHELL_RC"
fi

# 3. Initialize current directory (if not already set up)
if [ ! -f "BUILD_STATE.md" ]; then
  cat > BUILD_STATE.md << 'EOF'
# Project State (last updated)

## Architecture
- Not yet documented

## What works
- Not yet catalogued

## What's broken or incomplete
- Not yet catalogued

## Recent changes
- Initial setup

## Active decisions
- None yet
EOF
  cat > BUILD_LOG.md << 'EOF'
# Build Log

Chronological record of every Claude Code session and what was built, changed, or decided.

EOF
  echo "✓ BUILD_STATE.md + BUILD_LOG.md created in current directory"
else
  echo "✓ Build log already exists in current directory"
fi

echo ""
echo "Done. Logging is active for this project."
echo "For future projects: init-build-log (open new terminal first)"