skynet/claude-foundations
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit: Claude Code foundations and improvements research

Browse Source 
Conventions, community best practices research (Sept 2025 - March 2026),
and prioritized improvement backlog for Claude Code workflows.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Paul O'Reilly
2026-03-12 23:02:54 +13:00
commit a4967df815
14 changed files with 765 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

34
improvements/ci-cd-integration.md Normal file
View File

@@ -0,0 +1,34 @@
# CI/CD Integration
## Why This Matters
60%+ of teams adopting Claude Code now use headless mode (`claude -p`) for automation. The most productive pattern is interactive Claude for architecture/design while delegating routine reviews and migrations to headless CI.
## Current State
- No CI/CD integration with Claude Code
- Projects hosted on Gitea (not GitHub, so GitHub Actions patterns need adaptation)
## Patterns
### Headless Mode (`claude -p`)
Run Claude non-interactively in scripts or CI pipelines:
- `claude -p "Generate changelog from recent commits" --output-format json`
- `claude -p "Review this diff for security issues" < diff.txt`
- Useful for automated PR review, changelog generation, migration scripts
### Automated PR Review
Claude reviews PRs automatically on open/update (15-45 seconds per review). Would need a Gitea webhook + runner setup rather than GitHub Actions.
### Cross-Model Validation
Advanced pattern: global CLAUDE.md tells Claude to send diffs to Gemini/Codex for independent validation before committing. "High catch rate" reported by users.
### Compounding Engineering
Autonomous CI where Claude handles routine tasks (dependency updates, code style fixes, doc generation) with manual review before merging. Creates a self-improving flywheel.
## Gitea Considerations
Most community examples use GitHub Actions with `@claude` mentions. For Gitea:
- Gitea Actions (compatible with GitHub Actions syntax) could run headless Claude
- Webhook-based triggers for PR review
- Would need to evaluate Gitea MCP compatibility or build a simple API wrapper skill

65
improvements/claude-md-refinements.md Normal file
View File

@@ -0,0 +1,65 @@
# CLAUDE.md Refinements
## Why This Matters
CLAUDE.md is the agent's "constitution." Community consensus is clear: bloated files cause Claude to ignore instructions. The sweet spot is under 200 lines / 1,000 tokens. Your current file is 187 lines — right at the boundary.
## Current State
- 187 lines in `~/dev/claude/CLAUDE.md`
- Contains project conventions, secrets rules, scripting standards, process principles
- Well-structured but could benefit from pruning and restructuring
## What To Keep (High Value)
These earn their place because Claude cannot infer them:
- Bash commands with specific flags (build, test, deploy recipes)
- Code style rules that **differ from defaults** (only deviations)
- Architectural decisions specific to your project
- Common gotchas and non-obvious behaviours
- Testing instructions and preferred test runners
- Repository etiquette (branch naming, commit format)
- Lessons from past mistakes
## What To Remove or Move
These can be pruned because Claude discovers them automatically or they belong elsewhere:
| Item | Why Remove | Where It Goes |
|---|---|---|
| Folder structure descriptions | Claude reads directories | Nowhere — discoverable |
| Technology stack | Visible in package.json/imports | Nowhere — discoverable |
| Generic advice ("write clean code") | No actionable signal | Delete |
| Formatting/linting rules | Deterministic tools do this better | Hooks |
| Detailed process that's project-specific | Only relevant in that project | Project-level CLAUDE.md or skills |
| Secrets rules (repeated across projects) | Cross-project concern | Global `~/.claude/CLAUDE.md` |
| Gitea/SSH conventions | Cross-project concern | Global `~/.claude/CLAUDE.md` |
## Structural Improvements
### Guidance Over Prohibition
Change "Never do X" to "Prefer Y instead of X." Claude follows positive guidance better than negative constraints.
Before: "Never use placeholder values with `-e` for vars that template config files"
After: "Always source template variables from `inventory.yml`, not ad-hoc `-e` flags"
### Add Verification Commands
Boris from the Claude Code team says giving Claude explicit ways to check its own work "2-3x's output quality." Add a section listing verification commands per project type:
- `helm template` for Helm values
- `kustomize build` for overlays
- `curl --resolve` for endpoint testing
- Test commands, lint commands
### Use Emphasis for Critical Rules
Adding "IMPORTANT" or "YOU MUST" measurably improves adherence for rules that matter most. Use sparingly — if everything is critical, nothing is.
### Attention Distribution
Claude focuses most on the beginning and end of CLAUDE.md. Middle sections get less attention. Put your most critical rules at the top.
## Maintenance Cadence
- Review every 2-3 weeks (ask Claude to audit and suggest improvements)
- Growth pattern: catch mistake -> add rule -> promote frequent rules to permanent status
- Prune aggressively: if a rule hasn't prevented an issue in a month, remove it
- Each model release, review and remove rules the new model handles natively

41
improvements/community-resources.md Normal file
View File

@@ -0,0 +1,41 @@
# Community Resources
## Curated Repositories
| Repository | Description |
|---|---|
| [awesome-claude-code](https://github.com/hesreallyhim/awesome-claude-code) | The most comprehensive curated list of skills, hooks, commands, orchestrators, and tools |
| [awesome-claude-skills](https://github.com/travisvn/awesome-claude-skills) | Curated skills catalogue |
| [ykdojo/claude-code-tips](https://github.com/ykdojo/claude-code-tips) | 45 practical tips from basics to advanced, including custom skills |
| [claude-code-best-practice](https://github.com/shanraisshan/claude-code-best-practice) | Community best practices guide |
| [claude-code-showcase](https://github.com/ChrisWiles/claude-code-showcase) | Reference project with hooks, skills, agents, commands, and GitHub Actions |
| [VoltAgent/awesome-claude-code-subagents](https://github.com/VoltAgent/awesome-claude-code-subagents) | 100+ specialised subagent definitions |
| [solatis/claude-config](https://github.com/solatis/claude-config) | The Claude Code creator's personal setup and philosophy |
## Guides and Articles
| Resource | Key Insight |
|---|---|
| [Official Best Practices](https://code.claude.com/docs/en/best-practices) | Authoritative source, keep CLAUDE.md under 1,000 tokens |
| [HumanLayer Blog](https://www.humanlayer.dev/blog/writing-a-good-claude-md) | Under 60 lines ideal, 300 lines max |
| [alexop.dev Progressive Disclosure](https://alexop.dev/posts/stop-bloating-your-claude-md-progressive-disclosure-ai-coding-tools/) | Skills as context-on-demand, 82% token savings |
| [builder.io Claude MD Guide](https://www.builder.io/blog/claude-md-guide) | Layered configuration strategy |
| [okhlopkov.com Claude Code Setup](https://okhlopkov.com/claude-code-setup-mcp-hooks-skills-2026/) | MCP, hooks, and skills setup walkthrough |
| [blog.sshh.io Claude Code Features](https://blog.sshh.io/p/how-i-use-every-claude-code-feature) | Comprehensive feature walkthrough |
| [Boris (Anthropic) HN Tips](https://news.ycombinator.com/item?id=46256606) | Plan Mode 2-3x's results, verification 2-3x's quality |
| [24 Claude Code Tips Advent Calendar](https://dev.to/oikon/24-claude-code-tips-claudecodeadventcalendar-52b5) | Daily tips covering breadth of features |
## Community Scale
- **r/ClaudeCode**: 96K members, 4,200+ weekly contributors (3x r/Codex)
- **r/ClaudeAI**: Broader Claude discussion, usage limits are the dominant topic
- **r/vibecoding**: 89K members, rapid prototyping with Claude Code
- Claude Code generates 4x more Reddit discussion than competing tools
## Plugins and Hook Repos
| Resource | Description |
|---|---|
| [ryanlewis/claude-format-hook](https://github.com/ryanlewis/claude-format-hook) | Multi-language auto-formatting hook |
| [boostvolt/claude-code-lsps](https://github.com/boostvolt/claude-code-lsps) | Language Server integration for Python, TS, Rust, Go |
| [obra/superpowers](https://github.com/obra/superpowers) | 20+ production-proven workflow skills |

42
improvements/global-configuration.md Normal file
View File

@@ -0,0 +1,42 @@
# Global Configuration
## Why This Matters
A global `~/.claude/CLAUDE.md` provides cross-project defaults, eliminating duplication across project-level files. The community has converged on a layered configuration strategy.
## Current State
- No global `~/.claude/CLAUDE.md` exists
- Cross-project conventions (Gitea, secrets, SSH) are in the project-level `~/dev/claude/CLAUDE.md`
- `~/.claude/settings.json` contains only `{"model": "opus"}`
## Layered Configuration Model
| Layer | File | Scope | Checked In |
|---|---|---|---|
| Personal defaults | `~/.claude/CLAUDE.md` | All projects | No |
| Project shared | `./CLAUDE.md` | Team, per-project | Yes |
| Directory-specific | `./subdir/CLAUDE.md` | Loaded when working in subdir | Yes |
| Local overrides | `CLAUDE.local.md` | Machine-specific, gitignored | No |
| Path-scoped rules | `.claude/rules/*.md` | Conditional on file patterns | Yes |
| On-demand knowledge | `.claude/skills/*/SKILL.md` | Loaded only when relevant | Optional |
## Suggested Global CLAUDE.md Content
Move these from the project-level file to global:
- **Gitea conventions** — SSH aliases, remote URL format, org structure
- **Secrets folder rules** — read-only, never copy values, never pass as CLI args
- **Commit message format** — meaningful messages, small focused commits
- **Session behaviour** — "Do not allow implicit decisions — confirm with the user"
- **Response style** — concise, no trailing summaries, no unnecessary emojis
- **SOPS + age** as the standard encryption tool
- **Documentation standards** that apply across all projects (CLAUDE.md, MEMORY.md, FUTURE.md, README.md)
## Settings.json Improvements
Beyond `model`, consider:
- Hook definitions (see hooks-and-automation.md)
- MCP server registrations (see mcp-servers.md)
- Permission preferences for common tool calls

58
improvements/hooks-and-automation.md Normal file
View File

@@ -0,0 +1,58 @@
# Hooks & Automation
## Why This Matters
Hooks are the #1 "why didn't I do this sooner" recommendation across the community. Unlike CLAUDE.md rules (which Claude can forget mid-session), hooks **always execute**. They provide deterministic guardrails around non-deterministic AI behaviour.
Key principle: "Never send an LLM to do a linter's job. LLMs are expensive and slow compared to traditional linters."
## Current State
- No hooks configured in `~/.claude/settings.json`
- Formatting/linting rules live in CLAUDE.md as prose instructions
## Community Recommendations
### PostToolUse: Auto-Formatting
Run formatters automatically after every `Edit`/`Write` tool call. Eliminates all formatting rules from CLAUDE.md.
- `prettier --write` for JS/TS/JSON/YAML/MD
- `shfmt -w` for shell scripts
- `ruff format` for Python
- Plugin: `ryanlewis/claude-format-hook` supports multi-language detection
Configuration goes in `~/.claude/settings.json` under `hooks.PostToolUse`.
### PreToolUse: Security Gates
Block dangerous operations before they execute:
- Block writes to `.env`, `.key`, `.pem`, `secrets/`, lockfiles
- Block destructive commands (`rm -rf /`, `dd`, `mkfs`)
- Scan for API keys/credentials in file content before writes
- Block commits that include sensitive file patterns
### PreToolUse: Commit Validation
Wrap `Bash(git commit)` with test/lint validation. Only allow commits if checks pass. Forces Claude into "test-and-fix" loops until the build is green. This is considered the single most effective quality gate.
Important: **Don't block at write time** — blocking on `Edit`/`Write` confuses Claude mid-plan. Validate at commit time instead.
### PreCompact: Transcript Backup
Save conversation transcript before auto-compaction so context is never lost. Creates a timestamped backup in a known location. Pairs well with the auto-memory system.
Reference: https://yuanchang.org/en/posts/claude-code-auto-memory-and-hooks/
### Notification Hook
Desktop notifications when Claude finishes a long task or needs input. Useful when running background agents.
Plugin: `CC Notify` from awesome-claude-code.
## Anti-Patterns
- Don't add too many hooks — each one adds latency to every tool call
- Don't block on `Edit`/`Write` for linting — do it on `PostToolUse` (non-blocking) or at commit time
- Don't duplicate hook logic in CLAUDE.md — if a hook handles it, remove the prose rule

42
improvements/mcp-servers.md Normal file
View File

@@ -0,0 +1,42 @@
# MCP Servers
## Why This Matters
MCP (Model Context Protocol) servers extend Claude Code with external tool integrations. Community consensus: "If you're not using MCPs, you're driving a Ferrari in first gear." However, each registered MCP consumes context tokens even when unused, so be selective.
## Current State
- No MCP servers configured
## Must-Have (Community Consensus)
### Context7
The single most-recommended MCP server. Provides real-time, version-specific documentation for any library/framework. Solves the knowledge-cutoff problem — Claude gets accurate docs for the exact version you're using.
Particularly valuable for:
- Helm chart values schemas (change between versions)
- Kubernetes API changes
- Any rapidly-evolving ecosystem
### Sequential Thinking
Structured problem-solving for complex architectural decisions. Described as "like having a senior architect who thinks before coding." Useful for planning phases.
## Worth Considering
| MCP Server | Purpose | Relevance |
|---|---|---|
| **Playwright** | Browser automation, UI testing, screenshot capture | Useful if doing web projects |
| **GitHub/Gitea** | PR/issue management from terminal | Would need a Gitea-compatible MCP |
| **Supabase** | Database ops, migrations, SQL queries | If using Supabase |
## Key Insights
- **Start with 2-3 MCPs, not all of them.** Each one adds to context overhead.
- **MCP Tool Search (lazy loading)** reduces context usage by up to 95% — register many, only load what's needed.
- **Prefer Skills over MCPs for stateless tools.** MCPs are best for stateful environments (browser sessions, database connections, auth boundaries). Stateless CLI wrappers are better as Skills.
## Migration Pattern
The community is trending toward moving stateless tools from MCPs to simple CLIs documented in SKILL.md files. The "wrapper pattern" uses commands as thin entry points (~93 tokens) + skills as full implementations loaded on-demand, reducing startup context by ~64%.

46
improvements/multi-agent-patterns.md Normal file
View File

@@ -0,0 +1,46 @@
# Multi-Agent Patterns
## Why This Matters
Subagents are the most powerful tool for managing context — they explore in a separate context window, keeping the main conversation clean. However, multi-agent workflows are overkill for 95% of tasks and currently expensive.
## Current State
- Built-in subagent support available (Explore, Plan, general-purpose)
- No custom orchestration
- No multi-terminal patterns
## Patterns (Simplest to Most Complex)
### 1. Built-in Subagents (Already Available)
Delegate research, exploration, and file searches to subagents. They run in separate context windows and return summaries. This is the easiest win — just use the Agent tool more deliberately.
### 2. Git Worktrees for Parallel Work
Use `git worktree` to let multiple Claude instances work on separate branches without conflicts. Each instance has its own working directory but shares the git history.
### 3. The 4-Terminal Pattern
Simple but effective: 4 specialised Claude Code agents in separate VS Code / tmux terminals with distinct roles (e.g., planner, implementer, tester, reviewer). Often beats complex orchestrators.
### 4. Master-Clone Architecture
Rather than custom subagents with rigid workflows, use Claude's built-in `Task(...)` to spawn general-agent clones. Put key context in CLAUDE.md and let the agent orchestrate delegation dynamically.
### 5. Container Isolation
Local Claude Code controls another instance inside a Docker container via tmux — sandboxed autonomous worker for risky/destructive operations.
## Orchestration Tools
| Tool | Description |
|---|---|
| **Claude Squad** | Terminal app managing multiple Claude Code agents in separate workspaces |
| **Happy Coder** | Spawn and control multiple Claude Codes with push notifications |
| **Claude Swarm** | Launch a Claude Code session connected to a swarm of other agents |
| **Claude MPM** | 47+ specialised agents with PM orchestration and automatic task routing |
## When NOT to Use Multi-Agent
- Simple, single-file changes
- Tasks that take less than a few minutes
- When context window is not a constraint
- When the coordination overhead exceeds the work itself
The community consensus: master the single-agent workflow first. Multi-agent adds complexity and cost that only pays off for genuinely parallel, independent workstreams.

44
improvements/planning-and-workflow.md Normal file
View File

@@ -0,0 +1,44 @@
# Planning & Workflow
## Why This Matters
Boris from the Claude Code team: "Go back and forth with Claude until you like the plan before you let Claude execute. This easily 2-3x's results for harder tasks." The community-recommended paradigm is **PLAN -> TASK CREATION -> EXECUTE**.
## Current State
- CLAUDE.md mentions milestones and verification scripts (good)
- No explicit planning workflow documented
- Plan Mode available but not emphasised in workflow
## Recommended Workflow
### 1. Plan Mode (Shift+Tab twice)
Enter Plan Mode before any non-trivial task. Iterate on the plan until you're satisfied. Plans save to `~/.claude/plans/` for historical review. This is the single highest-ROI workflow change according to the Claude Code team.
### 2. Verification-Driven Development
Give Claude explicit ways to check its own work. Boris says this alone "2-3x's output quality."
- For Helm: `helm template` to validate values
- For Kubernetes: `kustomize build`, `kubectl --dry-run`
- For web: Playwright MCP or `curl --resolve`
- For code: test commands, lint commands, type-checking
- For infra: `scripts/verify-m<N>.sh` (you already do this well)
### 3. Test-Driven Development Loops
Let Claude write tests alongside code, then run them autonomously. The "write-test cycle" creates a self-healing loop:
1. Claude writes/modifies code
2. Runs tests
3. If tests fail, fixes code
4. Repeats until green
This is especially powerful with commit-gate hooks that prevent commits until tests pass.
### 4. The Stingraycharles Approach
The creator of Claude Code's personal workflow:
- "Do not allow the LLM to make any implicit decisions — confirm with the user"
- Planning phase takes 1+ hours for complex tasks, but catches issues early
- Structure code so AI can easily understand it ("LLM-friendly code")
- Document invisible knowledge that's difficult to infer from code alone
- Uses sub-agents plus reusable skills, with most skills invoking Python scripts
Reference: https://github.com/solatis/claude-config/

34
improvements/plugins-and-language-servers.md Normal file
View File

@@ -0,0 +1,34 @@
# Plugins & Language Servers
## Why This Matters
The community calls Language Server integration "the single biggest productivity gain" for Claude Code. LSPs give Claude real-time type information, go-to-definition, and find-references — dramatically improving code understanding over raw text analysis.
## Current State
- No LSP plugins installed
- No third-party plugins
## Language Server Plugin
**boostvolt/claude-code-lsps** — provides LSP integration for:
- Python (pyright)
- TypeScript (vtsls)
- Rust (rust-analyzer)
- Go (gopls)
This gives Claude access to the same intelligence your IDE uses: types, definitions, references, diagnostics. Particularly valuable for large codebases and unfamiliar code.
## Other Recommended Plugins
| Plugin | Purpose | Value |
|---|---|---|
| **obra/superpowers** | 20+ structured workflow skills (TDD, debugging, root cause tracing) | "Transforms Claude from reactive helper to proactive senior developer" |
| **commit-commands** | Intelligent commit messages generated from diffs | Consistent, meaningful commit history |
| **pr-review-toolkit** | Multi-agent code reviews with confidence scoring | Automated quality gates on PRs |
## Installation Considerations
- Plugins add to context overhead — evaluate each one's token cost vs. value
- Start with the LSP plugin alone and measure the improvement before adding more
- `obra/superpowers` overlaps with custom skills — evaluate which skills you'd use before installing the full set

38
improvements/session-and-context-management.md Normal file
View File

@@ -0,0 +1,38 @@
# Session & Context Management
## Why This Matters
Context is the most precious resource in a Claude Code session. The 200k token window seems large but fills fast — especially with MCP tools, long files, and multi-step tasks. Community consensus: managing context deliberately is a 2-3x productivity multiplier.
## Current State
- No explicit context management practices documented
- Auto-memory system is configured (built-in)
- No compaction hooks
## Key Practices
### Session Hygiene
- **Use `/clear` between unrelated tasks.** A fresh session costs ~20k tokens (10% of budget), leaving ~180k for work. Polluted context from failed approaches actively degrades output quality.
- **After two failed corrections, `/clear` and start fresh.** Context is now polluted with failed approaches. Write a better initial prompt instead.
- **One task per session.** The "kitchen sink session" (start task A, ask about B, return to A) is a documented anti-pattern.
### Context Budgeting
- **Use `/context` to audit token usage.** MCP tools consume context even when unused. Browser automation tools alone can eat 8-30% of available context.
- **Remove unused MCP servers** from settings when not actively needed.
- **Compact proactively at 60-70% usage** — don't wait for auto-compact.
### Extended Thinking
- **Only `ultrathink` activates extended thinking** as of Claude Code v2.0.0. Previous keywords like "think" or "think hard" no longer work.
- Use `ultrathink` for complex reasoning tasks, architectural decisions, and debugging subtle issues.
### Compaction Strategy
- Default reserves 32k tokens (22.5% of 200k) for auto-compact buffer.
- Setting `CLAUDE_CODE_MAX_OUTPUT_TOKENS` to 64k increases the buffer to ~40%.
- **PreCompact hook** (see hooks-and-automation.md) saves transcript before compaction.
- Pair with auto-memory: gradual learning via memory, emergency snapshots via PreCompact hooks.
### Handoff Between Sessions
- Before ending a long session, create a handoff document: goals, progress, blockers, next steps.
- A `/handoff` or `/catchup` skill (see skills-and-progressive-disclosure.md) automates this.
- "Context is like milk — keep it fresh and condensed."

59
improvements/skills-and-progressive-disclosure.md Normal file
View File

@@ -0,0 +1,59 @@
# Skills & Progressive Disclosure
## Why This Matters
Progressive disclosure is the single most powerful technique for managing context. Instead of putting everything in CLAUDE.md (which competes with Claude's ~50 built-in system instructions for attention), skills load domain knowledge **on demand** — only when relevant.
Token savings: ~15,000 tokens per session recovered vs. loading everything upfront (82% improvement in one benchmark).
## Current State
- One custom skill: `reflect`
- Skills symlinked from `~/dev/claude/custom-claude-skills/skills/` into `~/.claude/skills/`
## Architecture
```
CLAUDE.md # <200 lines, universal rules only
.claude/skills/ # Domain knowledge loaded on demand
.claude/rules/ # Path-scoped rules (YAML frontmatter for file pattern matching)
```
Skills use a three-stage loading: metadata (~100 tokens) -> full instructions (<5k tokens) -> bundled resources only as needed.
## Suggested Skills to Build
### /catchup
Reads all changed files in your git branch when resuming work. Shows what changed since last session, reads relevant memory files, and summarises the current state.
### /validate
Codifies the "validate before deploying" principle. Runs helm template, kustomize build, linting, and type-checking as appropriate for the current project. Catches errors before they hit the cluster.
### /deploy
Standardised deploy workflow for cluster-bootstrap. Validates first, applies, then runs the appropriate verify script.
### /security-audit
Checks for secrets in code, insecure configurations, default credentials. Trail of Bits has 12+ open-source security skills that could be adapted.
### /tdd
Test-driven development workflow. Write tests first, then implement until tests pass. From `obra/superpowers` — 20+ production-proven skills.
### /handoff
Creates a structured handoff document (goals, progress, blockers, next steps) for session transitions. Useful before `/clear` or when hitting context limits.
## Community Skills Worth Evaluating
| Skill/Resource | Description |
|---|---|
| **obra/superpowers** | 20+ skills: TDD, systematic debugging, root cause tracing, brainstorming |
| **Trail of Bits security skills** | 12+ security-focused skills for code auditing and vulnerability detection |
| **cc-devops-skills** | IaC validation, shell script generation, DevOps workflows |
| **Context Engineering Kit** | Advanced context engineering techniques with minimal token footprint |
| **reddit-fetch** | Workaround for Claude's inability to fetch Reddit — uses Gemini CLI as fallback |
## Best Practices
- Limit to 20-30 high-quality skills. More than that degrades performance (Claude wastes tokens parsing descriptions).
- Each skill should have one clear purpose and be self-contained.
- Skills should be <200 lines / <5k tokens for the full instruction set.
- Use YAML frontmatter in `.claude/rules/` for path-scoped conditional loading (e.g., rules that only apply to `*.yaml` files).