f41c22d0ac
- CLAUDE.md: add "Question the question" and "One clarifying question" rules to Tone and Interaction — XY problem detection, false premise checks, and explicit reframe pattern before answering - Add claude/ detail-file directory (topic docs referenced from CLAUDE.md) - Add ABOUT.md, FUTURE.md - Update memory/, scripts/, settings.yaml with accumulated session changes Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
62 lines
4.5 KiB
Markdown
62 lines
4.5 KiB
Markdown
# Process Lessons
|
|
|
|
## Always run git-status-report at session start
|
|
|
|
Previous sessions may leave uncommitted work. Running `git-status-report` (or checking git status) at session start catches this pattern before it compounds.
|
|
|
|
## Use plan mode for architectural tasks
|
|
|
|
Plan mode (Shift+Tab twice) works well for designing systems before implementing. Explore existing patterns, design the architecture, get approval, then execute. Implementation is straightforward when the plan is thorough.
|
|
|
|
## PostToolUse exit code 2 feeds errors back to Claude
|
|
|
|
Exit code 2 from a PostToolUse hook sends stderr content back to Claude as feedback without blocking the edit. Exit 0 = silent success. Exit 1 = hard block.
|
|
|
|
## Agent-type hooks are read-only
|
|
|
|
Hooks with `type: "command"` cannot use Edit/Write tools. Lint fixing from hooks must happen via the Agent tool subagent, not directly in hooks.
|
|
|
|
## All hooks in a matcher array run in parallel
|
|
|
|
Multiple hooks registered for the same matcher execute concurrently, not sequentially. Design hooks to be independent.
|
|
|
|
## SSH key for ai_enablement is password-protected
|
|
|
|
Needs ssh-agent loaded before git push to Gitea. If push hangs, check that the key is added to the agent.
|
|
|
|
## Research full failure history before building validators
|
|
|
|
When building a tool that detects known problems (like `validate-skill`), first research all historical failures across session logs and git commits. This reveals non-obvious patterns — e.g., `$HOME` (not just `${HOME}`) being rejected by permission checkers, which wouldn't be found from docs alone. The upfront research investment pays off in comprehensive coverage.
|
|
|
|
## Batch parallel file creation for efficiency
|
|
|
|
Creating many independent files in a single Write batch (e.g., 11 best-practices files at once) is significantly faster than sequential creation.
|
|
|
|
## Evaluate the right home for new content before building
|
|
|
|
Before creating a new system or document, discuss where it belongs conceptually (e.g., MEMORY.md vs SPEC vs dedicated catalog). Different content types have different lifecycles — accumulated learnings vs authoritative maintained maps vs behavioral contracts. Picking the wrong home means future maintenance friction.
|
|
|
|
## Add SSH-authenticating user as collaborator when creating repos via API
|
|
|
|
When creating Gitea repos via API token (e.g., `ai_admin`), the SSH alias may authenticate as a different user (e.g., `cluster-administrator`). Always add the SSH user as admin collaborator via API before pushing.
|
|
|
|
## Use background agents for parallel independent research
|
|
|
|
When researching multiple topics that don't depend on each other, launch background subagents simultaneously. Both API design and LLM security research completed in ~5 minutes each, producing structured output with citations. Review results as they complete. Don't duplicate research work the subagent is doing.
|
|
|
|
## Include more surrounding context when Edit tool matches are ambiguous
|
|
|
|
The Edit tool fails if `old_string` matches multiple locations. When editing files with repeated patterns (like FUTURE.md items that all end with "Depends on: M9"), include unique surrounding lines (a heading, the preceding paragraph) to disambiguate. Don't use `replace_all: true` as a workaround — it changes all instances.
|
|
|
|
## Best-practices repo is separate from claude-foundations
|
|
|
|
Best practices live in skynet/best-practices (cloned at ~/dev/claude/projects/best-practices/). ~/dev/claude/BESTPRACTICES.md is a symlink to its index. context-load doesn't show the best-practices directory in the tree — remember it exists when working on best practices topics.
|
|
|
|
## Keep skill and script symlinks in sync across all profiles
|
|
|
|
Every profile (`~/.claude`, `~/.claude-octopus`, `~/.claude-oreillyit`) is independent — missing a symlink in one profile breaks that profile's slash commands without affecting others. When adding or renaming a skill or skill-helper script, verify symlinks exist in every active profile. Example that bit: `~/.claude-octopus/skills/switch-mode` symlink was missing while `~/.claude/skills/switch-mode` worked. Audit with `ls -la ~/.claude*/skills/` when touching skill layout.
|
|
|
|
## Verify subagent output paths use the project's absolute path
|
|
|
|
When `/log` (or any skill that spawns a subagent) writes files on the project's behalf, always verify the first real run that the subagent wrote to the project's **absolute** `memory/log/` path, not a relative path resolved from an unexpected cwd. A relative path silently lands in the wrong directory and the log looks missing.
|