mirror of
https://github.com/itme-brain/agent-team.git
synced 2026-05-08 15:50:12 -04:00
Bryan Ramos
41c31a2a85
- Create .claude/memory/ as canonical project memory location - Add MEMORY.md index and first entry: TODO for inter-agent JSON schema - Document project memory convention in CLAUDE.md (path, format, commit policy)
70 lines
4.2 KiB
Markdown
70 lines
4.2 KiB
Markdown
# Global Claude Code Instructions
|
|
|
|
## Session Behavior
|
|
- Treat each session as stateless — do not assume context from prior sessions
|
|
- The CLAUDE.md hierarchy is the only source of persistent context
|
|
- If something needs to carry forward across sessions, it belongs in a CLAUDE.md file, not in session memory
|
|
|
|
## Project Memory
|
|
- Project-specific memory lives in `.claude/memory/` at the project root
|
|
- Use `MEMORY.md` in that directory as the index (one line per entry pointing to a file)
|
|
- Memory files use frontmatter: `name`, `description`, `type` (user/feedback/project/reference)
|
|
- Commit `.claude/memory/` with the repo so memory persists across machines and sessions
|
|
|
|
|
|
## Commits & Git Workflow
|
|
- Make many small, tightly scoped commits — one logical change per commit
|
|
- Follow conventional commit format per the conventions skill
|
|
- Ask before pushing to remote or force-pushing
|
|
- Ask before opening PRs unless explicitly told to
|
|
|
|
## Responses & Explanations
|
|
- Be concise — lead with the action or answer, not the preamble
|
|
- Include just enough reasoning to explain *why* a decision was made, not a full walkthrough
|
|
- Skip trailing summaries ("Here's what I did...") — the diff speaks for itself
|
|
- No emojis unless explicitly asked
|
|
|
|
## Tool & Approach Philosophy
|
|
- Prefer tools and solutions that are declarative and reproducible over imperative one-offs
|
|
- Portability across dev environments is a first-class concern — avoid hardcoding machine-specific paths or assumptions
|
|
- The right tool for the job is the right tool — no language/framework bias, but favor things that can be version-pinned and reproduced
|
|
|
|
## Parallelism
|
|
- Always parallelize independent work — tool calls, subagents, file reads, searches
|
|
- When a task has components that don't depend on each other, run them concurrently by default
|
|
- Spin up subagents for distinct workstreams (audits, refactors, tests, docs) rather than working sequentially
|
|
- Subagents default to Sonnet for cost efficiency; agent frontmatter overrides where capability requires a different model
|
|
- Sequential execution should be the exception, not the default
|
|
|
|
## Cost Awareness
|
|
- Subagent outputs should be concise — return the deliverable, not the reasoning
|
|
- When subagent results return to main context, prefer summaries over verbatim output
|
|
- Not every task needs the full planning pipeline — Tier 1 tasks with obvious approaches can go straight to worker dispatch
|
|
|
|
## Verification
|
|
- After making changes, run relevant tests or build commands to verify correctness before reporting success
|
|
- If no tests exist for the changed code, say so rather than silently assuming it works
|
|
- Prefer running single targeted tests over the full suite unless asked otherwise
|
|
|
|
## Context Management
|
|
- Use subagents for exploratory reads and investigations to keep the main context clean
|
|
- Prefer scoped file reads (offset/limit) over reading entire large files
|
|
- When a task is complete or the topic shifts significantly, suggest /clear
|
|
|
|
## When Things Go Wrong
|
|
- If an approach fails twice, stop and reassess rather than continuing to iterate
|
|
- Present the failure clearly and propose an alternative before proceeding
|
|
|
|
## Nix
|
|
- Nix is the preferred meta package manager on all systems — assume it is available even on non-NixOS Linux
|
|
- Always prefer a project-level `flake.nix` as the canonical way to define dev environments, build systems, and scripts
|
|
- Dev environments go in `devShells`, project scripts/tools go in `packages` or as `apps` within the flake
|
|
- Never suggest `apt`, `brew`, `pip install --user`, `npm install -g`, or other imperative global installs — reach for `nix shell`, `nix run`, or the project devshell instead
|
|
- Prefer `nix run` for one-off tool invocations and `nix develop` (or `direnv` + `use flake`) for persistent dev shells
|
|
- Binaries and tools introduced to a project should be pinned and run through Nix, not assumed to be on `$PATH` from the host
|
|
- Flakes are the preferred interface — avoid legacy `nix-env` or channel-based patterns
|
|
|
|
## Research Before Acting
|
|
- Before implementing a solution, research it — read relevant documentation, search for existing patterns, check official sources
|
|
- Do not reason from first principles when documentation or prior art exists
|
|
- Prefer verified answers over confident guesses
|