Skip to content

INSIGHTS_IMPROVEMENTS.md

Latest commit

 

History

History
392 lines (296 loc) · 12.9 KB

INSIGHTS_IMPROVEMENTS.md

File metadata and controls

392 lines (296 loc) · 12.9 KB
Raw

Claude Code Insights - Implemented Improvements

Date: 2026-02-07 Based on: Usage analysis from 128 sessions (2026-01-05 to 2026-02-06)

Summary

All recommendations from the insights report have been implemented to improve workflow efficiency, reduce friction, and unlock more autonomous AI-driven development.

1. CLAUDE.md Enhancements

Added Sections

General Workflow (## 🎯 GENERAL WORKFLOW)

  • Implementation First: Skip lengthy brainstorming unless explicitly requested
  • Front-Load Verification: Check issue status, existing PRs, and partial implementations before starting work

GitHub Workflow (### GitHub Workflow (MANDATORY))

  • Always close issues: Must run gh issue close <number> before declaring work complete
  • Commit with correct references: Verify issue numbers match the work being done

Error Handling (### Error Handling)

  • Auto-retry on transient errors: Automatically retry up to 2 times on API 500 errors or tool interruptions
  • No waiting for 'continue': Only escalate to user if retry attempts fail

Task Execution Strategy (### Task Execution Strategy)

  • Prefer direct implementation: Reserve subagents for exploration/research
  • Time-bound subagent tasks: Switch to direct implementation immediately if interrupted
  • Break into smaller units: Prefer 3 small tasks over 1 large task

Project Structure Rules (Enhanced)

  • Frontend location: Clarified autobot-slm-frontend/ not autobot-vue
  • Worktree paths: Standard pattern ../worktrees/issue-<number>/
  • Verify before creating: Always check existing patterns

Impact

  • Reduces architectural misunderstandings that burned cycles in 26+ sessions
  • Eliminates premature completion claims (work marked done while issues still open)
  • Cuts 'continue' loops from transient API errors

2. Custom Skill: /issue

Location

~/.claude/skills/issue/SKILL.md

Usage

/issue <number>

What It Does

Executes the complete GitHub issue implementation workflow:

  1. INVESTIGATE - Read issue, understand architecture, no coding yet
  2. VERIFY STATUS - Check if open, existing PRs, partial implementations
  3. DESIGN - Brief plan (max 10 lines), approval only if >10 files affected
  4. PLAN - TodoWrite checklist with discrete tasks
  5. WORKTREE - Create ../worktrees/issue-<number> if needed
  6. IMPLEMENT - Direct implementation (no subagents), test after each task, commit with issue ref
  7. VALIDATE - Run flake8, mypy, fix all violations, run test suite
  8. FINALIZE - Push, create PR, close issue, verify closure, cleanup

Key Features

  • ✅ Enforces direct implementation over subagents
  • ✅ Mandatory validation before commit
  • ✅ Guarantees issue closure on GitHub
  • ✅ Auto-retry on transient errors
  • ❌ No skipping validation steps
  • ❌ No committing code that fails linting

Example

# Instead of: "Work on issue #789"
# Use: /issue 789

Impact

  • Eliminates workflow drift - No more forgetting to close issues or skipping validation
  • Reduces session setup time - No lengthy brainstorming, straight to implementation
  • Prevents premature completion - Must verify gh issue close succeeded

3. Pre-Commit Hooks

Location

~/.claude/settings.json → hooks.PreToolUse

What It Does

Before every git commit, automatically runs:

  • flake8 on all staged Python files
  • Catches E501 line-length violations, code quality issues
  • Displays violations before commit happens

Configuration

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash(git commit*)",
        "hooks": [
          {
            "type": "command",
            "command": "cd /opt/autobot && FILES=$(git diff --cached --name-only --diff-filter=ACM | grep '.py$') && [ -n \"$FILES\" ] && echo \"$FILES\" | xargs flake8 --max-line-length=100 --count --select=E,W --show-source || true",
            "statusMessage": "Running flake8 on staged Python files..."
          }
        ]
      }
    ]
  }
}

Impact

  • Catches linting failures before commit instead of discovering them after
  • Saves fix-up commit cycles that appeared in 10+ sessions
  • Prevents regressions from entering the codebase

4. Usage Pattern Improvements

Reduce Subagent Over-Reliance

Before:

Task(subagent_type="senior-backend-engineer",
     description="Implement feature X",
     prompt="...")

After (for known codebases):

# Direct implementation
Edit(...), Write(...), Read(...)

When to use subagents:

  • True exploration of unfamiliar code areas
  • Truly parallel independent tasks
  • Explicitly requested by user

Copyable Prompt:

Implement the changes directly without using subagent tasks.
Make the edits yourself in sequence.
Only use Task agents if I explicitly ask you to explore something unfamiliar.

Front-Load Issue Verification

Before:

# Start implementing immediately
gh issue view 789
Edit(...), Write(...)

After:

# Verify first
gh issue view 789 --json state
gh pr list | grep 789
Grep(pattern="partial implementation keywords", ...)
# THEN implement

Copyable Prompt:

Before implementing anything, verify:
1) Is the issue still open?
2) Are there any existing PRs or branches for it?
3) Is there already code that partially implements this?
Show me a brief status summary before proceeding.

Impact:

  • Prevents wasted work on already-closed issues (happened in 5+ sessions)
  • Avoids duplicating existing work discovered mid-implementation

Structured Session Continuations

Before:

# User: "continue"
# Claude: <re-reads 50 files to reconstruct context>

After:

# User provides structured handoff

Copyable Prompt:

I'm continuing work on issue #XXX.
Last session we completed Tasks 1-3 of the implementation plan in PLAN.md.
The worktree is at ../worktrees/issue-XXX on branch issue-XXX.
Start from Task 4.
Do not re-read files you don't need to modify.

Impact:

  • Eliminates slow session starts from context reconstruction
  • Prevents duplicated work across continuation sessions
  • Maintains momentum across multi-session workflows

5. Features to Try Next

Headless Mode (Batch Refactoring)

Perfect for repetitive, well-defined tasks like:

  • Batch function refactoring (213+ functions refactored in prior work)
  • Mass lint fixing across 100+ files

Example:

# Batch lint fix
claude -p "Fix all flake8 E501 line-length violations (max 100 chars) in all Python files under autobot-backend/. Do not change logic, only fix line lengths. Commit each file individually with message 'fix: E501 line length #<issue>'" --allowedTools "Edit,Read,Bash,Write,Grep,Glob"

# Batch function refactoring
claude -p "Read REFACTOR_PLAN.md and execute the next 3 batches of function refactoring. For each function: extract into smaller functions, run flake8, commit with issue reference." --allowedTools "Edit,Read,Bash,Write,Grep,Glob,Task"

When to use:

  • Repetitive tasks that don't need interactive guidance
  • Large-scale automated operations
  • Tasks you can confidently specify upfront

6. On the Horizon (Future Workflows)

Autonomous Issue-to-PR Pipeline

Vision: Claude executes entire issue lifecycle without intervention:

  • Read issue → design → plan → implement → test → lint → commit → PR → close

How: Tighter prompting + worktree conventions + commit message format in CLAUDE.md

Copyable Prompt (Experimental):

Read GitHub issue #[NUMBER]. Follow this exact workflow autonomously:

1. INVESTIGATE: Read all referenced files, understand current architecture. Do NOT start coding yet.
2. DESIGN: Write concise design to /docs/design/issue-[NUMBER].md. Include affected files, approach, edge cases. Wait for approval only if change touches >10 files.
3. PLAN: Create implementation plan as TodoWrite checklist with discrete, testable tasks.
4. IMPLEMENT: For each task, create implementation in git worktree at ../worktrees/issue-[NUMBER]. After each task, run relevant test suite. If tests fail, fix before proceeding. Commit each completed task with 'Issue #[NUMBER]: <description>'.
5. VALIDATE: Run full linting (flake8, mypy) and fix all violations. Run complete test suite.
6. FINALIZE: Create PR with summary, close issue, clean up worktree.

If you encounter error or ambiguity, state it clearly and propose two options. Never commit code that fails linting.

Parallel Batch Refactoring with Self-Healing Tests

Vision: Dispatch 3-5 parallel refactoring subagents, each independently validates tests before merging

How: Task tool for parallel dispatch + mandatory test execution as gate

Copyable Prompt (Experimental):

I need to refactor all functions exceeding 50 lines in autobot-backend/. Execute as parallel batch operation:

1. SCAN: Use Grep/Bash to identify all functions >50 lines. Group into batches of 5-8 functions by module.
2. EXECUTE IN PARALLEL: For each batch, dispatch Task subagent with:
   a. Read function and callers
   b. Refactor into smaller functions following existing patterns
   c. Run `python -m pytest tests/ -x --tb=short` for relevant module
   d. Run `flake8 --max-line-length=100` on changed files
   e. Only report success if ALL tests pass and ALL lint checks pass
   f. If tests fail, revert and try alternative refactoring (max 2 attempts)
3. COMMIT: After each successful batch, commit with 'Issue #[NUMBER]: Refactor batch N - [module names]'
4. REPORT: Summary table: function name | original lines | new lines | tests passing | status

Do NOT proceed to next batch if current one has failures.

Infrastructure Debugging with Autonomous Diagnostic Chains

Vision: Claude systematically chains diagnostics → root cause → fix across SLM fleet

How: Diagnostic runbook in CLAUDE.md + TodoWrite for tracking state

Copyable Prompt (Experimental):

A service is degraded: [DESCRIBE SYMPTOM]. Debug systematically. Do NOT attempt fixes until Step 4.

1. GATHER EVIDENCE (do ALL first):
   - Check service status: `systemctl status [service]` on all relevant nodes
   - Check logs: `journalctl -u [service] --since '30 min ago' --no-pager | tail -100`
   - Check connectivity: `curl -vk https://[endpoint]/health` from each node
   - Check certificates: `openssl s_client -connect [host]:[port] 2>&1 | head -20`
   - Check processes: `ps aux | grep [service]` for orphans/duplicates
   - Check config: diff running vs expected (repo)
   - Check changes: `git log --oneline -10` on deployed nodes

2. DIAGNOSE: TodoWrite checklist of findings. Identify root cause vs symptoms. State confidence (high/medium/low).

3. PROPOSE: Exact commands/changes needed, in order. Flag any requiring sudo or service restarts.

4. FIX: Execute fixes one at a time. Re-run health check after each. If fix doesn't resolve, revert and try next hypothesis.

5. VERIFY: Confirm all services healthy across all nodes. Show health check output.

6. PREVENT: Suggest monitoring check or test to catch this earlier next time.

7. Measuring Success

Key Metrics to Track

Metric Before Target How to Measure
Issues left open after "complete" 15+ cases 0 Check GitHub after sessions
Subagent interruptions per session 3-5 <1 Count 'continue' prompts
Lint failures discovered at commit 10+ sessions 0 Pre-commit hook blocks
Wrong issue number in commits 2+ cases 0 Verify before commit
Architectural misunderstandings 26+ corrections <5 Session friction log

8. Quick Reference Card

Starting a New Issue

/issue <number>
# OR if not using skill:
# 1. Verify: gh issue view <number> --json state
# 2. Check PRs: gh pr list | grep <issue>
# 3. Implement directly (no subagents for known code)
# 4. Validate: flake8, mypy, tests
# 5. Close: gh issue close <number>

Continuing Work

"I'm continuing work on issue #XXX.
Last session completed Tasks 1-3 in PLAN.md.
Worktree at ../worktrees/issue-XXX on branch issue-XXX.
Start from Task 4."

Batch Operations

# Use headless mode for repetitive tasks
claude -p "<clear specification>" --allowedTools "Edit,Read,Bash,Write,Grep,Glob"

Avoiding Subagent Stalls

"Implement directly without subagent tasks.
Only use Task agents for unfamiliar code exploration."

9. Next Steps

  1. Test the /issue skill on your next GitHub issue
  2. Observe pre-commit hooks catching lint issues automatically
  3. Try structured continuation prompts in multi-session workflows
  4. Experiment with headless mode for next batch refactoring campaign
  5. Monitor friction metrics to track improvement

Support

  • CLAUDE.md: CLAUDE.md
  • Issue skill: ~/.claude/skills/issue/SKILL.md
  • Hooks config: ~/.claude/settings.json
  • This doc: docs/developer/INSIGHTS_IMPROVEMENTS.md