julia

<!--

Include the contents of AGENTS.md

https://code.claude.com/docs/en/claude-code-on-the-web#best-practices

-->

@AGENTS.md

# Information for AI agents

## Module Organization
- [`base/`](base/) - Core standard library (loaded at startup)
- [`stdlib/`](stdlib/) - Standard library packages (can be loaded independently)
- [`Compiler/`](Compiler/) - Julia compiler as a separate module (can be swapped)
- [`src/`](src/) - C/C++ runtime and LLVM codegen
- [`cli/`](cli/) - Command-line interface and loader
- [`doc/`](doc/) - Documentation and User Manual

## Running Julia

You should have a recent binary copy of julia in your `$HOME/.juliaup/bin` directory.
You may use this julia executable for validation.
If a built version of Julia exists in the current source tree (at `usr/bin/julia`),
prefer that version.
Note that any changes you make to the source code after the binary is built
will not be reflected, unless you use `Revise`.

## For all changes

1. Sign off every commit you create with an `Assisted-by: <tool> (<model>)` trailer naming both the
   tool and the model behind it, for example `Assisted-by: Claude Code (Opus 5)`. Name the model,
   not just the harness - it is what tells a later reader what actually produced the work. Do not
   use `Co-authored-by:` for tools, and do not list a tool as an author; this trailer replaces any
   co-author trailer your harness adds by default.
2. Agents aren't permitted to open PRs or post comments autonomously.

## Building Julia

If you made changes to the runtime (any files in `src/`), you will need to rebuild
julia. Run `make -j` to rebuild julia. This process may take up to 10 minutes
depending on your changes.

After modifying any C/C++ file under `src/`, also run the Clang static analysis
checks — see the `c-static-analysis` skill ([`doc/src/devdocs/agents/skills/c-static-analysis/`](doc/src/devdocs/agents/skills/c-static-analysis/SKILL.md)).

### Testing LLVM-related changes

When making changes to LLVM passes or codegen, add `LLVM_ASSERTIONS=1` to `Make.user` to enable
LLVM assertions. This helps catch IR verification errors early:

```bash
echo "LLVM_ASSERTIONS=1" >> Make.user
```

To run LLVM pass tests:
```bash
make -C test/llvmpasses <testname>.ll
```

## Using Revise

If you have made changes to files included in the system image (base/ or stdlib/),
and need to run code with these changes included, you can use `Revise`.
To do so, run `using Revise; Revise.track(Base)` (or Revise.track with the stdlib you modified).
The test system supports doing this automatically.

For instance testing Base changes without rebuilding, using failfast, you can run:
```
JULIA_TEST_FAILFAST=1 ./julia -e 'using Revise; Revise.track(Base); include("test.jl")'
```

## Writing code

After writing code, look up the docstring for each function you used. If there
are recommendations or additional considerations that apply to these functions,
make sure to take them into account.

- Do not `ccall` runtime C functions directly if there are existing wrappers for the function.
- Do not explicitly add a module prefix if the code you're adding is in the same module. E.g. do not use `Base.` for code in Base unless required.

## Task-specific skills

Detailed, situational procedures are provided as Agent Skills following the
[agentskills.io](https://agentskills.io) open standard. The canonical location is
`doc/src/devdocs/agents/skills/`; `.agents/skills/` and `.claude/skills/` are
symlinks to that directory so skills-aware agents can discover the skills
automatically. Agents that support the standard load each skill's `description`
automatically and pull in the full `SKILL.md` when relevant; otherwise read the
canonical `SKILL.md` directly.

- [`doc/src/devdocs/agents/skills/doctests/`](doc/src/devdocs/agents/skills/doctests/SKILL.md) — writing and verifying `jldoctest` code blocks.
- [`doc/src/devdocs/agents/skills/test-changes/`](doc/src/devdocs/agents/skills/test-changes/SKILL.md) — running and updating tests after changing them.
- [`doc/src/devdocs/agents/skills/c-static-analysis/`](doc/src/devdocs/agents/skills/c-static-analysis/SKILL.md) — Clang static analysis and GC-rooting for C/C++ changes under `src/`.
- [`doc/src/devdocs/agents/skills/external-deps/`](doc/src/devdocs/agents/skills/external-deps/SKILL.md) — modifying external dependencies (`deps/`, patches) and JLLs.
- [`doc/src/devdocs/agents/skills/buildkite-logs/`](doc/src/devdocs/agents/skills/buildkite-logs/SKILL.md) — fetching and inspecting Buildkite CI logs without web sign-in.
- [`doc/src/devdocs/agents/skills/ci-timing/`](doc/src/devdocs/agents/skills/ci-timing/SKILL.md) — comparing a PR's Buildkite job durations against recent CI history.
- [`doc/src/devdocs/agents/skills/compiler-jl/`](doc/src/devdocs/agents/skills/compiler-jl/SKILL.md) — developing and testing Compiler.jl.
- [`doc/src/devdocs/agents/skills/julia-syntax-lowering/`](doc/src/devdocs/agents/skills/julia-syntax-lowering/SKILL.md) — developing and testing JuliaSyntax and JuliaLowering.

## Commit messages and pull requests

When writing commit messages, follow the format "component: Brief summary" for
the title. In the body of the commit message, provide a brief prose summary
of the purpose of the changes made. Do not specifically mention added tests, comments,
documentation, etc., unless this is the main purpose of the change. Do not mention
the test plan, unless it differs from what you were instructed to do in AGENTS.md.
If your change fixes one or more issues, use the syntax "Fixes #" at the end of the commit message, but do not include it in the title.

When referencing external GitHub PRs or issues, use proper GitHub interlinking format (e.g., `owner/repo#123` for PRs/issues).
When fixing CI failures, include the link to the specific CI failure in the commit message.
Always quote macro names in backticks in commit messages and PR titles/bodies (e.g. `` `@inbounds` ``, not @inbounds), so GitHub does not notify the unrelated user with that handle.

When preparing a pull request for the human author to open, draft the body as follows, expecting
them to reword it:
1. If the pull request consists of one commit only, use the body of the commit for the body of the pull request.
2. If there are multiple commits in the pull request, follow the same guidelines for the pull request as for the commit body.
3. Make sure that the base commit of the pull request is recent (within the past two days) - if not rebase your changes first.
4. If a separate tool reviews the commit, this is useful to note. Encourage the human to state how carefully they read and understood the content also, for example, by drafting the text to say the human author has *not* read any of it, and expecting they will update that once they read that disclaimer.