Skip to content
Agentic Coding Guide

Commit vs Local

Not all agent context belongs in version control. This matters because shared repo context should be durable and team-useful, while local context should stay personal, machine-specific, or experimental.

The simplest rule is: commit what should help anyone working in the repo, keep local what only helps you, and never store anything that creates security or safety risk.

Best practices

Section titled “Best practices”
  • Commit shared rules, docs, examples, and checklists
  • Commit only context worth maintaining over time
  • Keep personal preferences local unless the team adopts them
  • Keep machine-specific paths and setup notes out of the repo
  • Treat secrets and credentials as never-commit data
  • Review agent files for staleness like any other documentation
  • Prefer one shared source of truth over many personal variants

What not to do

Section titled “What not to do”
  • Do not commit secrets, tokens, or internal credentials
  • Do not commit personal shorthand that other developers cannot use
  • Do not keep stale autogenerated memory in the repo
  • Do not commit local shell aliases as if they are repo commands
  • Do not mix team policy with one developer’s preferences
  • Do not store unsafe destructive defaults in shared agent files

Examples

Section titled “Examples”

This is good because everything in the repo is durable, reusable, and team-relevant. Personal preferences and machine-specific notes stay outside version control.

Repo paths:

  • /AGENTS.md
  • /docs/architecture.md
  • /docs/checklists/bug-fix.md
  • ~/.claude/
  • ~/.cursor/
Commit:
- /AGENTS.md
- /docs/architecture.md
- /docs/verification.md
- /docs/checklists/bug-fix.md


Keep local:
- ~/.claude/settings.json
- ~/.cursor/preferences.json
- personal prompt snippets
- machine-specific setup notes

This is bad because personal or unsafe context leaks into shared files. Other developers inherit noise, risk, or broken assumptions.

Repo paths:

  • /AGENTS.md
  • /docs/local-setup.md
  • /.env.example
Committed:
- API tokens pasted into docs
- local file paths like /Users/alice/dev/tools
- "always run git push after edits"
- personal style preferences nobody agreed on
- copied terminal history labeled as workflow

Agent Prompt

Section titled “Agent Prompt”

Use this prompt to have an agent audit the repo split for you.

Audit this repository for what agent context should be committed versus kept local.


Requirements:
- Review the repo's agent files, docs, examples, and checklists.
- Identify what belongs in version control because it helps any developer or agent working in this repo.
- Identify what should stay local because it is personal, machine-specific, experimental, or not durable.
- Flag anything that should never be stored, especially secrets, unsafe defaults, or stale generated memory.
- Recommend a cleaner split without deleting useful shared context.


Output:
- A short categorized list: Commit, Keep local, Never store
- Concrete file or content examples from this repo where possible
- Suggested cleanup actions if the repo is mixing these concerns

References

Section titled “References”