chore: add AGENTS.md files #2608
Conversation
This change introduces four new `AGENTS.md` files to provide guidance to AI agents working with the Outline codebase. - The root `AGENTS.md` explains the overall repository structure, the `npm run action` command, and common concepts. - `client/AGENTS.md` provides specialized information about the client applications, including directory structure, key technologies, and build/test instructions. - `server_manager/AGENTS.md` focuses on the server management components, covering its architecture, APIs, and build/test instructions. - `infrastructure/AGENTS.md` details the project's build system, explaining how to extend it with new actions. This also includes corrections to the example commands based on the GitHub workflow files and additional information from the README.md files.
There was a problem hiding this comment.
Pull Request Overview
This PR adds documentation files for AI agents across the Outline monorepo to improve development workflow and onboarding. The documentation provides structural overviews, build instructions, and development guidelines for each major component.
- Added AGENTS.md files to root directory and three main components (client, server_manager, infrastructure)
- Documented directory structures, key technologies, and build/test commands for each component
- Provided comprehensive guide for the custom
npm run actionbuild system
Reviewed Changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| AGENTS.md | Root-level guide introducing the monorepo structure and common npm run action commands |
| client/AGENTS.md | Client-specific documentation covering Electron, Cordova, and web development workflows |
| server_manager/AGENTS.md | Server Manager documentation for web and Electron app development |
| infrastructure/AGENTS.md | Infrastructure documentation explaining the build system and action creation |
Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.
| * **Run**: `npm run action server_manager/electron/start ${PLATFORM}` | ||
| * **Run with development build**: `BUILD_ENV=development npm run action server_manager/electron/start ${PLATFORM}` | ||
|
|
||
| Where `${PLATFORM}` is one of `linux`, `macos`, `windows`. If ommitted, it assumes the host platform. |
There was a problem hiding this comment.
There's a spelling error: 'ommitted' should be 'omitted'.
| Where `${PLATFORM}` is one of `linux`, `macos`, `windows`. If ommitted, it assumes the host platform. | |
| Where `${PLATFORM}` is one of `linux`, `macos`, `windows`. If omitted, it assumes the host platform. |
| To enable error reporting through [Sentry](https://sentry.io/) for local builds, run: | ||
|
|
||
| ```bash | ||
| export SENTRY_DSN=[Sentry DNS URL] |
There was a problem hiding this comment.
The acronym should be 'DSN' (Data Source Name), not 'DNS URL'. The comment should read '[Sentry DSN URL]'.
| export SENTRY_DSN=[Sentry DNS URL] | |
| export SENTRY_DSN=[Sentry DSN URL] |
There was a problem hiding this comment.
Not sure it needs to know this? Unless we wanna give it a DSN to use.
There was a problem hiding this comment.
This is a good start. FYI, you've also been using github copilot - I don't think it supports AGENTS.md (they only crawl the files they're told to crawl), but I think you can add a file at .github/copilot-instructions.md and simply point it to the AGENTS.md file. Something like this to start:
# Copilot Instructions
## Project Overview
This project contains an architectural overview and rules of conduct in several `AGENTS.md` files.
## File Locations
- `AGENTS.md`
- `cilent/AGENTS.md`
- `infrastruction/AGENTS.md`
- `server_manager/AGENTS.md`
## Expectations
Always reference `AGENTS.md` for guidance on:
- Project structure
- Common concepts
- Technologies uesd
- Additional reosources
| * **Cordova**: Used to build the clients for macOS, iOS, Android. | ||
| * **[Lit](https://lit.dev/)**: a simple library for building fast, lightweight web components, core to the client's web-based components. | ||
| * **Polymer**: The legacy UI framework used before Lit. | ||
| * **TypeScript**: Used for all web-based code. |
There was a problem hiding this comment.
Might be worth including information on GTS/how we write typescript here at Google?
|
|
||
| ## Key Technologies | ||
|
|
||
| * **Lit**: The primary UI framework for the Server Manager's web-based components. |
| To enable error reporting through [Sentry](https://sentry.io/) for local builds, run: | ||
|
|
||
| ```bash | ||
| export SENTRY_DSN=[Sentry DNS URL] |
There was a problem hiding this comment.
Not sure it needs to know this? Unless we wanna give it a DSN to use.
| @@ -0,0 +1,35 @@ | |||
| # Welcome to the Outline Monorepo! | |||
|
|
|||
| This document provides a guide for AI and human agents working with the Outline codebase. | |||
There was a problem hiding this comment.
Possibly worth linking this in the README, for humans
|
Thanks for the feedback. I put this in draft because I realized that there's too much overlap with the README files. I don't think it makes sense to maintain both. I think a better approach will be to cleanup the READMEs to make it more helpful for both humans and AI, and create symlinks from AGENTS.md to the README. I haven't been using copilot to generate code, so it doesn't matter much to me, but we could also add the copilot file as a symlink. |
I like this approach for now, though I think people have been decoupling them because it allows human-facing documentation to be warmer/fuller (more human-friendly) while agent-facing documentation can be specifically optimized for LLMs (sometimes with weirdly specific or redundant phrasing they respond better to) |
2 participants
I'm hoping this will make it easier to use AI agents.