> ## Content Index > Fetch the complete content index at: https://jonathancanales.com/llms.txt > Use this file to discover other available public pages before exploring further. # Claude Code: Teamwork and Best Practices - URL: https://jonathancanales.com/en/claude-code-teamwork-best-practices/ - Published: 2026-08-14T14:00:00.000Z - Updated: 2026-10-25T21:10:33.000Z - Description: Shared memory, versioned permissions and human review: the foundation for Claude Code to pay off on a team. - Author: Jonathan Canales - Tags: #en, Technology and tools In August 2026, Claude Code has moved from each programmer's personal tool to a shared piece of the team: the same agent reads the repository, proposes changes and takes part in code review for several people at once. That jump changes the conversation. Knowing how to use the agent is the starting point; the real challenge is getting the whole team to use it coherently, with the same rules, the same permissions and the same review standard. Teams that solve this turn the agent into a stable multiplier, and teams that improvise it end up with five different configurations and unpredictable results. This guide collects the practices that separate one scenario from the other. ![Doodle of an open notebook with a fountain pen, the nib orange](https://jonathancanales.com/content/images/2026/10/pair18-doodle1.png) ## The project contract: CLAUDE.md Every serious collaboration with Claude Code starts in the CLAUDE.md file, the project memory the agent reads at the beginning of each session. On a team, that file becomes the contract between people and agent: it holds the build and test commands, the style conventions, the repository structure and the rules the agent must always respect. The official memory documentation describes how Claude Code loads that file and how its project, user and local versions are layered. Three practices make CLAUDE.md pay off on a team. The first is versioning it in the repository like any other critical file: every change goes through review, and the file's history explains why each rule exists. The second is keeping it short and current: fifty precise lines outperform three hundred that mix the essential with the historical, and a monthly file review fits inside the usual retrospective. The third is writing it in the imperative with examples: "run tests with make test" guides the agent better than a vague description of the test system. Each member's personal file covers everything else: individual preferences, aliases and shortcuts that belong to each workflow and travel in the user configuration, separate from the shared contract. That split between shared and personal is the team's first architecture decision. ## Shared permissions and configuration Claude Code's settings system spreads across several levels with clear precedence: versioned project settings, local project settings and user settings. The settings documentation details that hierarchy, and using it well avoids half of team friction. The versioned project level is the right place for the allowed-commands list: the operations the agent can run directly, such as running tests, building or formatting. When that list lives in the repository, every member works with the same limits and the agent behaves the same on every machine. The local and user levels stay individual: personal paths, personal tools, model preferences. The practical rule is simple: if a permission affects what lands in the repository, it belongs to the shared configuration; if it only affects one person's comfort, it belongs to their personal configuration. Reviewing that boundary when someone joins saves days of surprises. ## Review flow with agents The healthy team pattern is the same as with any collaborator: the agent proposes, a person reviews, and the branch merges after tests pass. In practice that means Claude Code works on branches, opens bounded and documented changes, and human review reads the full diff before approving. Commit messages follow the team's convention, because the agent writes them according to the instructions in CLAUDE.md. Two habits reinforce that flow. The first is asking the agent for a plan before execution: a short description of which files it will touch and why, which a person reviews before authorizing the writes. The second is keeping tasks bounded: an agent modifying three files with a clear goal produces ten-minute reviews, while a broad request produces diffs nobody reads carefully. The quality of human review is the real limit of the system, and everything that protects it multiplies the agent's value. ## Automation with GitHub Actions The Claude Code integration with GitHub Actions brings the agent to the place where the team already talks: issues and pull requests. With it, mentioning the agent in a comment assigns it a task, and the workflow configured in the repository runs the agent with the permissions and context the team defined. The official GitHub Actions documentation describes the installation and options of that workflow. On a team, that automation pays off most when it starts with repetitive, well-bounded, high-volume tasks: triaging issues, proposing first versions of small changes, summarizing long pull requests for the reviewer. Each new automation enters with an observation period, and the ones that prove value stay. Pull requests opened by the agent go through the same human review as any other, always, because team trust is built on verified diffs. ![Doodle of two coffee mugs with a shared clipboard, one checkbox ticked orange](https://jonathancanales.com/content/images/2026/10/pair18-doodle2.png) ## Shared conventions: AGENTS.md and skills CLAUDE.md coexists with AGENTS.md, the open convention several agents read to understand a project. Teams using more than one tool usually keep AGENTS.md as the common source of instructions and leave Claude Code specifics in CLAUDE.md, with cross-references to avoid duplicates drifting apart. Shared skills take the convention a step further: they package team procedures, like a report format or the steps of a deploy, into files any member invokes the same way. The guide on [what skills are and how to create one](https://jonathancanales.com/en/claude-skills-what-they-are-how-to-create) covers the mechanics, and the comparison between [skills and repeated prompts](https://jonathancanales.com/en/claude-skills-vs-repeated-prompts) explains when a frequent instruction deserves to become a skill. For the team, the criterion is the same as with any shared code: one versioned and reviewed skill beats ten prompts saved in personal notes. ## Individual habits that scale to the team The personal best practices, described in the [commands and shortcuts guide](https://jonathancanales.com/en/claude-code-most-used-commands-shortcuts) and in Anthropic's best-practices documentation, become team practices when they are written down and shared. Working in small tasks, reading every diff, giving the agent full context and correcting it early are habits a team adopts as norms: they come up during onboarding, they are modeled in reviews and they are reinforced in retrospectives. Plugins and extensions complete the shared ecosystem: a team that standardizes its review tooling and integrations works in a homogeneous environment, and the [plugins and extensions guide](https://jonathancanales.com/en/claude-code-plugins-extensions) helps choose them. The general rule holds: whatever affects the shared outcome gets decided together and versioned. ## Bringing someone new into the flow The acid test of a team setup is onboarding a new member. With CLAUDE.md versioned and permissions in the repository, that onboarding shrinks to cloning, reading the project contract and running a first bounded task with close review. The first week is for observing: the newcomer reads agent-produced diffs, compares their expectations with the result and learns the team's conventions on real ground. The second week reverses the roles: they request the tasks and someone experienced reviews their instructions before execution, correcting the level of detail and the size of each request. That accompanied learning costs two weeks and prevents months of diverging habits. Teams that document it in the onboarding guide discover a side benefit: explaining the flow to another person is the best audit of the system itself, because every rule that is hard to explain marks a spot to simplify. ## Measurement and continuous improvement A team adopting an agent needs to know whether the adoption pays. The useful metrics are the usual flow ones: pull-request cycle time, the share of reviews requesting corrections from the agent, tasks completed per week with and with assistance. The own-project comparison method, described in [testing a tool with your own project](https://jonathancanales.com/en/best-ai-for-coding-test-tool-own-project), works the same at team scale: same tasks, same metrics, a decision with evidence. Continuous improvement closes the circle: each month the team reviews which CLAUDE.md rules were used, which permissions are surplus and which are missing, which skills got invoked and which sat forgotten. The contract with the agent evolves with the project, and that versioned evolution is, in the end, the practice that sustains all the others. One thing makes everything above possible: writing. A team that adopts Claude Code soon discovers its most valuable assets are short, careful texts, the project memory, the permissions list, the conventions and the skills. Those texts are written once, reviewed like code and pay off in every agent session, for every member, every day. A final word on pace. Teams that succeed with Claude Code grow usage gradually: one shared configuration, one automated workflow, one reviewed skill at a time. Each addition gets a trial period, a metric and a decision, which keeps the system understandable for everyone who joins later. The teams that struggle are usually the ones that automated ten things in the first week and can barely say which rule produced which behavior. ## A practical close Claude Code on a team works when three things are written and versioned: the project memory, the shared permissions and the review conventions. With that scaffolding, the agent behaves the same for everyone, every change passes through human eyes and automation grows on proven tasks. The result is a team where AI adds speed and people keep the judgment, a combination that takes deliberate work to build and that any team can reach within a few weeks of steady practice. ## Sources - [Anthropic: Claude Code best practices](https://www.anthropic.com/engineering/claude-code-best-practices?ref=jonathancanales.com) - [Claude Code memory documentation](https://code.claude.com/docs/en/memory?ref=jonathancanales.com) - [Claude Code settings documentation](https://code.claude.com/docs/en/settings?ref=jonathancanales.com) - [Claude Code and GitHub Actions](https://code.claude.com/docs/en/github-actions?ref=jonathancanales.com) - [AGENTS.md, instruction convention for agents](https://agents.md/?ref=jonathancanales.com)