Skip to content

Commit 24716d0

Browse files
authored
Add section on using LLMs to CONTRIBUTING.md (#5211)
This adds a section on using LLMs to the CONTRIBUTING.md guide, including how to connect to a MCP that knows about AMReX's documentation. The proposed changes: - [ ] fix a bug or incorrect behavior in AMReX - [ ] add new capabilities to AMReX - [ ] changes answers in the test suite to more than roundoff level - [ ] are likely to significantly affect the results of downstream AMReX users - [ ] include documentation in the code and/or rst files, if appropriate
1 parent 1f20ab8 commit 24716d0

File tree

1 file changed

+51
-5
lines changed

1 file changed

+51
-5
lines changed

CONTRIBUTING.md

Lines changed: 51 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
Development generally follows the following ideas:
44

5-
* New features are merged into to the `development` branch using
5+
* New features are merged into the `development` branch using
66
Pull Requests (PRs).
77

88
Nightly regression testing is used to ensure that no answers
@@ -156,15 +156,15 @@ your fork, with your `<branch_name>`.
156156
- It is time to communicate your changes: write a title and a description for
157157
your PR. People who review your PR are happy to know
158158
* what feature/fix you propose, and why
159-
* how you made it (created a new class than inherits from...)
159+
* how you made it (created a new class that inherits from...)
160160
* and anything relevant to your PR (performance tests, images, *etc.*)
161161
- Press `Create pull request`. Now you can navigate through your PR, which
162162
highlights the changes you made.
163163

164164
Please DO NOT write large Pull Requests, as they are very difficult and
165165
time-consuming to review. As much as possible, split them into small,
166166
targeted PRs.
167-
For example, if find typos in the documentation open a pull request that only fixes typos.
167+
For example, if you find typos in the documentation open a pull request that only fixes typos.
168168
If you want to fix a bug, make a small pull request that only fixes a bug.
169169
If you want to implement a large feature, write helper functionality first, test it and submit those as a first pull request.
170170
If you want to implement a feature and are not too sure how to split it,
@@ -250,15 +250,15 @@ parenthesis of the parameter list (but not when simply calling the function). Fo
250250
These guidelines should be adhered to in new contributions to AMReX, but
251251
please refrain from making stylistic changes to unrelated sections of code in your PRs.
252252

253-
To help developers follow the idententation and whitespace guidelines, an
253+
To help developers follow the indentation and whitespace guidelines, an
254254
[EditorConfig](https://editorconfig.org/) file is provided at
255255
[.editorconfig](.editorconfig).
256256

257257
### API Documentation Using Doxygen
258258

259259
The Doxygen documentation is designed for advanced user-developers. It aims
260260
to maximize the efficiency of a search-and-find style of locating information.
261-
Doxygen style comment blocks should proceed the namespace, class, function, etc.
261+
Doxygen style comment blocks should precede the namespace, class, function, etc.
262262
to be documented where appropriate. For example:
263263
```cpp
264264
/**
@@ -276,3 +276,49 @@ void MyFunction (int variable, MultiFab& data)
276276
```
277277
Additional information regarding Doxygen comment formatting can be found
278278
in the [Doxygen Manual](https://www.doxygen.nl/manual/).
279+
280+
## LLM-assisted workflows
281+
282+
Large Language Models (LLMs) can assist with AMReX development by helping to understand the existing
283+
codebase, writing new code, reviewing pull requests, finding bugs, and adding tests and documentation.
284+
This section of the developer's guide documents how the AMReX repository is configured for LLM-based coding assistants
285+
and how to get the most out of them.
286+
287+
> **_NOTE:_** LLMs can hallucinate and sometimes produce code that compiles and runs but is incorrect. LLM-written code should
288+
be manually reviewed with care before opening a pull request. Please respect the AMReX maintainers' time by making sure you understand
289+
any bot-generated code before requesting a review.
290+
291+
### Best Practices
292+
293+
When working with LLM coding assistants, keep in mind that *"most best practices are based on one constraint: [the] context window fills up fast, and performance degrades as it fills"* ([Claude Code Best Practices](https://code.claude.com/docs/en/best-practices)).
294+
Starting from examples and iterating incrementally — as described below — helps keep sessions focused and productive.
295+
296+
1. **Start small and iterate incrementally.**
297+
Run your coding assistant inside the AMReX source directory.
298+
Point the assistant to an existing function, Test, or example code and ask it modify it, gradually adding complexity and verifying along the way.
299+
300+
2. **Write a test.**
301+
Give the agent a way to verify its work. Often, the agent itself can write tests first, then implement functionality.
302+
303+
3. **Be specific in your prompts.**
304+
Reference specific files, tell the agent where to look for code patterns, and describe specific cases to test.
305+
306+
### Connecting to a documentation Context through an MCP Server
307+
308+
A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server is a standardized way to provide external context, such as library documentation, to LLM-based coding assistants.
309+
When an MCP server is configured, the assistant can query up-to-date AMReX documentation on demand, rather than relying solely on its training data. This is helpful because agents might otherwise rely on out-of-date information from their training data and/or have to read too many files into their contexts to perform development tasks.
310+
311+
### Setting Up Context7 as an MCP Server
312+
313+
[Context7](https://context7.com) is a service that indexes open-source project documentation and serves it through the MCP protocol.
314+
AMReX documentation is available at:
315+
316+
- **AMReX**: [context7.com/amrex-codes/amrex](https://context7.com/amrex-codes/amrex)
317+
318+
Once connected, a coding assistant (Claude Code, Cursor, VS Code Copilot, Windsurf, etc.) can retrieve relevant sections of the AMReX documentation in real time when helping you develop applications and inputs files.
319+
320+
pyAMReX documentation is also available at:
321+
322+
- **pyAMReX**: [context7.com/amrex-codes/pyamrex](https://context7.com/amrex-codes/pyamrex)
323+
324+
For popular coding assistants, see the [Context7 documentation](https://context7.com/docs/resources/all-clients) to configure [AMReX](https://context7.com/amrex-codes/amrex).

0 commit comments

Comments
 (0)