config/skills/coding-agent/NOTES.md

Claude Code Usage Notes

Golden Rule

User gives task → spawn sub-agent → sub-agent runs Claude Code → sub-agent verifies → user gets ONE summary message. No play-by-play.

How to Use Claude Code

Via Sub-Agent (preferred for complex tasks)

sessions_spawn with task like:
"Run Claude Code to [task]. Working dir: /path/to/project.
After Claude Code finishes, verify the changes compile and make sense.
If not, run Claude Code again with fixes. Commit and push when done."

Direct (simple tasks only)

cd /path/to/project
claude -p "task description" --allowedTools "Edit,Write,Bash"

Key Facts

• Default model: Opus 4.6 (no override needed)
• Auth: OAuth login already completed, no API key needed
• Allowed tools: Always pass --allowedTools "Edit,Write,Bash"
• Timeout: Claude Code can take 5-20 minutes for complex tasks. Don't micromanage.
• Hanging: Sometimes streams hang after ~10-15 min. Sub-agent can detect this and retry.
• PTY mode: Use pty=true when running via exec

Sub-Agent Task Template

Run Claude Code CLI in /path/to/project to do the following:

[TASK DESCRIPTION]

Steps:
1. Run: cd /path/to/project && claude -p "[task]" --allowedTools "Edit,Write,Bash"
2. Wait for completion (up to 20 min, check if process is still alive periodically)
3. If it hangs (no file changes for 10+ min), kill and retry once
4. After completion, verify: go build / npm build / etc
5. If build fails, run Claude Code again with the error
6. Commit and push when everything works
7. Report summary of all changes made

Anti-Patterns

• ❌ Polling every 30 seconds and reporting progress
• ❌ Sending WhatsApp messages during the process
• ❌ Reading every file before/after to narrate changes
• ✅ Fire and forget, verify at end, report once