8. Apply your conventions across projects

8. Apply your conventions across projects

You should not have to explain the same coding, modeling, or writing preferences whenever you begin a project. Global user instructions let the agent reuse those conventions while keeping each study’s question, data, and decisions in its own records. Corrections made during one project can then improve work on the next.

For example, you might ask the agent to save results at full precision and report uncertainty alongside estimates. Those conventions can apply to many papers. A decision to restrict one survey analysis to respondents aged 18 and over belongs in that paper’s SPECIFICATION.md, with the reason recorded in METHODOLOGY.md.

Decide which conventions apply across projects

Global user instructions establish default behaviors across your projects. When a project needs an exception, record it in that project’s CLAUDE.md1 and tell the agent to follow it for that project. For example, your usual writing conventions might specify American spelling, while a particular journal requires British spelling.

Save instructions that describe a recurring way of working. “Preserve the existing software environment and explain any required package change” is more useful than “be reproducible.” A good shared instruction tells the agent what to do in a recognizable situation. It should leave study-specific choices to the project.

Global user instructions can also point to reference information, such as the software already installed or the locations of related projects. Keeping an inventory is different from prescribing a rule, but both can prevent the agent from making unnecessary guesses.

The ~/.claude/ folder holds global user instructions. CLAUDE.md lists paths to WRITING.md, CODING.md, MODELING.md, and CONVENTIONS.md and says when to read them. Separate paper and website folders have their own project context files; the website uses DESIGN.md.
Figure 1

Organize detailed guidance by subject

The global CLAUDE.md acts as a hub: it holds shared defaults and gives the agent paths to specialist files, with instructions on when to read them. Give each specialist file a clear purpose. The following examples cover common research needs; add the files that are useful to your work.

File When to consult it Example content
CONVENTIONS.md Creating or organizing a project. Folder layouts for papers, datasets, and websites; names for inputs and outputs.
CODING.md Writing or changing code. Use project-relative paths, reusable functions, and the existing package environment.
MODELING.md Planning, fitting, or checking statistical models. Specify the estimand; use the required simulation checks and uncertainty summaries.
WRITING.md Drafting or editing prose. State the point directly, define unfamiliar terms, and remove repeated explanations.
TOOLCHAIN.md Adding or troubleshooting software. Available tools, their configurations, and how they are maintained.
WORKSPACE.md Finding a project or shared input. Project purposes, folder locations, and dependencies between projects.

Start with the conventions you repeatedly explain. Separate a topic when its detail makes the global instruction file hard to read. For instance, a manuscript edit needs the writing guidance but may not need several pages of statistical conventions. These filenames do not cause the agent to load their contents automatically; the main instructions (see below) must point to them.

Have the agent create and use global user instructions

In Claude Code, global user instructions live in ~/.claude/CLAUDE.md, outside individual project folders.2 Here, ~ means your home folder. Ask the agent to create or update this file from the app, using the practices you describe or examples of work you have accepted.

Use these conventions and examples to create or update ~/.claude/CLAUDE.md. Keep it concise and link to specialist files, stating when each should be read. Keep study-specific decisions in the project context files. Show me proposed changes before applying them.

~/.claude/CLAUDE.md should tell the agent which specialist file to read for each kind of task. For example:

Before editing code, read CODING.md beside this file.
Before statistical modeling or simulation, read MODELING.md.
Before drafting prose, read WRITING.md.
Read each project's context files for its scientific decisions and current state.
Follow explicit project-specific exceptions to these conventions.

The complete shared example provides a starting point. Ask the agent to adapt it to your work and then apply the relevant guidance during the next real task. You can assess whether a paragraph follows your writing conventions or whether an analysis used the existing software environment. A file’s presence alone does not show that the agent used it.

Download global user instructions

Read the complete global user instructions
# Global user instructions

[Describe your research role and the software you normally use.]

## Before a task
- Read the relevant project context files. Preserve accepted work.
- Identify the requested result, constraints, and evidence needed to accept it.
- Ask about consequential ambiguity; do not silently substitute another analysis.

## Conventions
These conventions are defaults across projects. Follow explicit project-specific
exceptions and record their reasons. Ask when instructions conflict and no
exception has been agreed.

[Keep short defaults here. Add paths or links only to files you maintain,
with their locations and when to read them. Possible topics include project
structure, coding, statistical modeling, writing, software, and project locations.]

Read the referenced guidance relevant to the task. If a listed file is missing,
report it; do not create a replacement or invent its instructions.

## Research work
- Preserve original data. Derive new files with saved code.
- Use independently runnable steps with declared inputs and outputs.
- For paper projects, keep current requirements in SPECIFICATION.md and dated
  scientific decisions and reasons in METHODOLOGY.md.
- Verify observed outputs before reporting success. Keep failed checks visible.

## Limits
- Use only inputs and services approved for the project.
- Ask before publishing, sending messages, expanding access, or adding a service.
- Do not delete recovery copies or rewrite shared history without approval.

## Finishing
- Update TASKS.md and STATUS.md from the work and checks actually completed.
- Report what changed, how it was checked, and what remains unresolved.

Maintain and share the conventions

When the same correction recurs, ask the agent to update the relevant shared guidance. For example, repeated rounding of saved model estimates can become an instruction to save full precision and round only for display. Review the proposed rule to make sure it applies beyond the current paper.

A research group can maintain shared files in a repository and make a local copy available to each member’s agent. Ask the agent to add the locations of the shared specialist files to ~/.claude/CLAUDE.md and specify when to read each one. Have it flag any conflicting instructions. A shared folder is useful only if sessions know when to read its contents.

Record a paper-specific exception in that project’s files, with its reason. A new research group default should not silently change a completed analysis. Keep one maintained copy of each shared rule, and use Appendix B: Keep records of shared settings: chezmoi in the companion guide Extending Your Agent’s Toolkit if you need to keep those files consistent across computers.

Footnotes

  1. If you use an agent from another provider, record the exception in AGENTS.md if that is the project instructions file the agent reads.↩︎

  2. Anthropic calls these user instructions. Other agent tools may use AGENTS.md in a different location: Codex, for example, uses ~/.codex/AGENTS.md by default. Ask the agent to confirm the location for the tool you use.↩︎