mirror of
https://github.com/XRPLF/rippled.git
synced 2026-06-03 08:46:46 +00:00
123 lines
3.8 KiB
Markdown
123 lines
3.8 KiB
Markdown
# doc-agent
|
|
|
|
Automated documentation agent for the xrpld C++ codebase. Built on the
|
|
Claude Agent SDK.
|
|
|
|
## What it does
|
|
|
|
Three modes:
|
|
|
|
- **document** — Add Doxygen `/** */` documentation to a C++ file or
|
|
directory. For each target file, the agent reads the sibling
|
|
`<file>.ai.md` (high-signal prose generated by the athenah-ai pipeline),
|
|
the module skill, and the file itself, then writes Doxygen comments per
|
|
the standards in `docs/DOCUMENTATION_STANDARDS.md`.
|
|
- **review** — Given a git diff range, detect documentation drift. Used by
|
|
the `doc-review` GitHub Action and locally for testing.
|
|
- **regen-skills** — Rebuild a module's skill file at
|
|
`docs/skills/soul/<module>.md` from the `.ai.md` files in that module
|
|
and the existing skill content.
|
|
|
|
## Requirements
|
|
|
|
- Node.js >= 20.12 (for native `--env-file` support)
|
|
- `ANTHROPIC_API_KEY` (in `.env` or exported in shell)
|
|
- Tools the agent uses: `git`, `gh` (for `--pr`)
|
|
|
|
## Install
|
|
|
|
```sh
|
|
cd .github/scripts/doc-agent
|
|
npm install
|
|
cp .env.example .env
|
|
# edit .env and set ANTHROPIC_API_KEY
|
|
```
|
|
|
|
The npm scripts auto-load `.env` via Node's `--env-file-if-exists` flag.
|
|
You can also export the variables in your shell — both work.
|
|
|
|
## Build and lint
|
|
|
|
```sh
|
|
npm run typecheck # type check without emitting
|
|
npm run build # compile to dist/
|
|
npm run lint # biome lint
|
|
npm run format # biome format --write
|
|
npm run check # lint + format check (read-only)
|
|
npm run check:fix # lint + format + fix
|
|
```
|
|
|
|
## Usage
|
|
|
|
```sh
|
|
# Document a single file (reads sibling .ai.md if present)
|
|
npm run document include/xrpl/basics/base_uint.h
|
|
|
|
# Document an entire module
|
|
npm run document include/xrpl/basics/
|
|
|
|
# Review a git range
|
|
npm run review develop..HEAD
|
|
|
|
# Review a PR
|
|
npm run review -- --pr 1234
|
|
|
|
# Regenerate a skill file from this module's .ai.md inputs
|
|
npm run regen-skills protocol
|
|
npm run regen-skills ledger
|
|
```
|
|
|
|
When invoked outside the xrpld repo, set `XRPLD_ROOT` in `.env` to the path
|
|
of the checkout you want to operate on.
|
|
|
|
## ai.md context files
|
|
|
|
The doc-agent reads a sibling `<file>.ai.md` next to each source file when
|
|
documenting it. These are produced by the upstream `athenah-ai` pipeline
|
|
and treated as the authoritative source of intent. They are gitignored
|
|
(`*.ai.md` in `.gitignore`) and should be removed once the initial
|
|
documentation pass is complete.
|
|
|
|
## Outputs
|
|
|
|
The `review` mode writes two files in the current directory:
|
|
|
|
- `doc-review-report.md` — markdown summary, posted as the PR comment
|
|
- `doc-review-comments.json` — array of inline review comments, posted
|
|
individually on the PR diff
|
|
|
|
## Layout
|
|
|
|
```
|
|
doc-agent/
|
|
├── package.json
|
|
├── tsconfig.json
|
|
├── biome.json
|
|
├── prompts/
|
|
│ ├── document-file.md # System prompt for documentation mode
|
|
│ ├── review-diff.md # System prompt for review mode
|
|
│ └── regen-skill.md # System prompt for regen-skills mode
|
|
└── src/
|
|
├── index.ts # CLI entry point
|
|
├── config.ts # Paths, model, module-skill map
|
|
├── prompt-loader.ts # Loads prompts + module skill context
|
|
├── document.ts # Document mode
|
|
├── review.ts # Review mode
|
|
├── regen-skills.ts # Regen-skills mode
|
|
└── types.ts # Shared types
|
|
```
|
|
|
|
## Module skills
|
|
|
|
The agent injects per-module context from `docs/skills/soul/*.md` into its
|
|
system prompt based on the file path being processed. The mapping lives in
|
|
`src/config.ts` (`MODULE_SKILL_MAP`).
|
|
|
|
## Notes
|
|
|
|
- Prompts live in markdown files, not source, so they can be edited without
|
|
touching code.
|
|
- The `document` mode uses `permissionMode: 'acceptEdits'` so the agent
|
|
writes directly to the target files. Run against a clean git tree so you
|
|
can review and revert if needed.
|