start agents.md to guide coding assistants #6134

groovecoder · 2025-12-17T17:56:28Z

This PR fixes #.

How to test:

~~l10n changes have been submitted to the l10n repository, if any.~~
~~I've added a unit test to test for potential regressions of this bug.~~
I've added or updated relevant docs in the docs/ directory.
~~All UI revisions follow the coding standards, and use Protocol / Nebula colors where applicable (see /frontend/src/styles/colors.scss).~~
Commits in this PR are minimal and have descriptive commit messages.

jwhitlock

Thanks @groovecoder. I feel like this is premature, and I'd prefer that you and other AI users collab outside the repo before committing. I am not an AI user, so I've done no testing of this file.

I suspect 500 lines is way too much, and will only work well with frontier models with large windows. I think 50 would be more appropriate.

More uninformed comments follow.

agents.md

joeherm

This looks good to me- I think it's worth having a discussion as a team before we merge it. I've played around with claude using the agents.md in the branch and think that it's giving good answers.

groovecoder · 2026-01-08T12:44:18Z

Okay I did a significant refactor here.

I reduced the total content of instructions from around 3K lines to 769 lines. I also split those over a number of even smaller files (all about 100 lines or less) so agents can load only the instructions they need. And the smaller instructions should fit better into smaller local models' context windows.
I also added AGENTS.md to be more compatible with more agents, including opencode.
I removed the instructions about ops completely - I agree we don't want any agents performing any ops.
I removed almost all of the code examples and file listings instructions, as those can go out-of-date quickly, and agents seem good at exploring the codebase without using many tokens or time.
I removed a number of "common tasks" that were not common, as those are likely to pollute the context window.

Vinnl

Thanks for splitting it up, made it a bit more manageable for me. Gave some input on the frontend and testing piece.

.agents/agents.testing.md

.agents/agents.frontend.md

joeherm

Looks great- thanks for splitting it up.

jwhitlock

The markdown paths seem sloppy, but maybe this is standard for LLM stuff, so I stopped after a while. Don't wait for my approval.

jwhitlock · 2026-01-09T15:40:49Z

.agents/agents.backend.md

+
+The backend is organized into Django apps.
+
+Check for an `.agents.md` file in an app directory for detailed guidance for that app.


looks like it is called agents.md, not .agents.md

jwhitlock · 2026-01-09T15:41:55Z

.agents/agents.backend.md

+- [privaterelay/.agents.md](privaterelay/.agents.md) - Core Django, settings, middleware, management commands
+- [api/.agents.md](api/.agents.md) - REST API, authentication, serializers
+- [emails/.agents.md](emails/.agents.md) - Email masking, AWS integration, metrics
+- [phones/.agents.md](phones/.agents.md) - Phone masking, Twilio integration


Files are agents.md (like privaterelay/agents.md), not .agents.md (like privaterelay/.agents.md). File is one folder up from here. So, should be something like:

[privaterelay/.agents.md](../privaterelay/agents.md)

jwhitlock · 2026-01-09T15:45:30Z

.agents/agents.backend.md

+- [.agents.md](.agents.md) - Project overview and global principles
+- [.agents/agents.frontend.md](.agents/agents.frontend.md) - Frontend development
+- [.agents/agents.testing.md](.agents/agents.testing.md) - Testing guidance


paths are wrong here too

jwhitlock · 2026-01-09T15:45:46Z

.agents/agents.backend.md

+- `docs/` - Comprehensive architecture documentation
+- `README.md` - Full setup instructions


path appear wrong here too

jwhitlock · 2026-01-09T15:46:45Z

.agents/agents.md

+
+### Single Frontend Static HTML Export
+
+The frontend is built **once** and deployed to **all environments** (dev, stage, prod). Environment-specific values **cannot be baked into the build**. See "Environment-specific configuration" in [agents.backend.md](agents.backend.m) for more details. Next.js generates static HTML served by Django/Whitenoise. No server-side rendering. Dynamic routes must be handled carefully.


path is agents.backend.md, not agents.md

jwhitlock · 2026-01-09T15:48:58Z

CLAUDE.md

@@ -0,0 +1,5 @@
+# Agent Lightbeam - Project Context


q: what is Agent Lightbeam?

whoops, different project. nice catch.

EMMLynch

@groovecoder, thanks for the effort here and splitting out the agent files. Looks good.

groovecoder · 2026-01-09T17:43:08Z

The markdown paths seem sloppy, but maybe this is standard for LLM stuff, so I stopped after a while. Don't wait for my approval.

Nah the paths were sloppy because I tried to manually fix all the references after I split up and moved the files. When I told claude to do it, it did a much more thorough job cleaning them up. Updated.

groovecoder requested review from Vinnl, joeherm, jwhitlock and vpremamozilla December 17, 2025 17:56

groovecoder force-pushed the start-agents branch from 7d7bc63 to 296e420 Compare December 17, 2025 19:18

jwhitlock reviewed Dec 18, 2025

View reviewed changes

joeherm reviewed Dec 22, 2025

View reviewed changes

agents.md Outdated Show resolved Hide resolved

joeherm reviewed Dec 22, 2025

View reviewed changes

agents.md Outdated Show resolved Hide resolved

joeherm reviewed Dec 22, 2025

View reviewed changes

agents.md Outdated Show resolved Hide resolved

joeherm approved these changes Dec 22, 2025

View reviewed changes

groovecoder self-assigned this Dec 29, 2025

groovecoder force-pushed the start-agents branch 12 times, most recently from 55e6d45 to 4debb9c Compare January 8, 2026 12:35

Vinnl reviewed Jan 8, 2026

View reviewed changes

groovecoder force-pushed the start-agents branch from 4debb9c to 7b31620 Compare January 8, 2026 22:24

joeherm approved these changes Jan 9, 2026

View reviewed changes

jwhitlock reviewed Jan 9, 2026

View reviewed changes

EMMLynch self-requested a review January 9, 2026 16:06

EMMLynch approved these changes Jan 9, 2026

View reviewed changes

start agents.md to guide coding assistants

8c35d59

groovecoder force-pushed the start-agents branch from 7b31620 to 8c35d59 Compare January 9, 2026 17:41

vpremamozilla approved these changes Jan 9, 2026

View reviewed changes

groovecoder enabled auto-merge January 9, 2026 17:49

groovecoder added this pull request to the merge queue Jan 9, 2026

Merged via the queue into main with commit 8487a23 Jan 9, 2026
30 checks passed

groovecoder deleted the start-agents branch January 9, 2026 18:10


		The backend is organized into Django apps.

		Check for an `.agents.md` file in an app directory for detailed guidance for that app.

		- `docs/` - Comprehensive architecture documentation
		- `README.md` - Full setup instructions


		### Single Frontend Static HTML Export

		The frontend is built once and deployed to all environments (dev, stage, prod). Environment-specific values cannot be baked into the build. See "Environment-specific configuration" in [agents.backend.md](agents.backend.m) for more details. Next.js generates static HTML served by Django/Whitenoise. No server-side rendering. Dynamic routes must be handled carefully.

start agents.md to guide coding assistants #6134

start agents.md to guide coding assistants #6134

Uh oh!

Conversation

groovecoder commented Dec 17, 2025

Uh oh!

jwhitlock left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

joeherm left a comment

Choose a reason for hiding this comment

Uh oh!

groovecoder commented Jan 8, 2026

Uh oh!

Vinnl left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

joeherm left a comment

Choose a reason for hiding this comment

Uh oh!

jwhitlock left a comment

Choose a reason for hiding this comment

Uh oh!

jwhitlock Jan 9, 2026

Choose a reason for hiding this comment

Uh oh!

jwhitlock Jan 9, 2026

Choose a reason for hiding this comment

Uh oh!

jwhitlock Jan 9, 2026

Choose a reason for hiding this comment

Uh oh!

jwhitlock Jan 9, 2026

Choose a reason for hiding this comment

Uh oh!

jwhitlock Jan 9, 2026

Choose a reason for hiding this comment

Uh oh!

jwhitlock Jan 9, 2026

Choose a reason for hiding this comment

Uh oh!

groovecoder Jan 9, 2026

Choose a reason for hiding this comment

Uh oh!

EMMLynch left a comment

Choose a reason for hiding this comment

Uh oh!

groovecoder commented Jan 9, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants