52b0f2b5c6
Session log for 2026-03-29 covering API/LLM security research, agent-runtimes audit, and review skill creation. Reflected into: - decisions.md: best-practices topic split, review skills read-only design - process-lessons.md: background agents for research, Edit context disambiguation, best-practices repo location Pruned 2 old reflected logs (2026-03-17, 2026-03-18). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
3.5 KiB
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.