docs: Add developer documentation, AGENTS.md #6448

khvn26 · 2025-12-31T07:05:18Z

Thanks for submitting a PR! Please check the boxes below:

I have added information to docs/ if required so people know about the feature!
I have filled in the "Changes" section below?
I have filled in the "How did you test this code" section below?
I have used a Conventional Commit title for this Pull Request

Changes

In this PR, we attempt to revamp our developer documentation, and make it accessible for human contributors and LLM-based agents alike.

Add AGENTS.md
Add missing developer documentation
Refresh CONTRIBUTING.md
Refresh the PR template
Import developer docs and CONTRIBUTING.md to docs.flagsmith.com

How did you test this code?

Mainly, observed with make -C docs serve.
TODO: report on AGENTS.md performance.

- Add missing developer documentation - Refresh CONTRIBUTING.md - Refresh the PR template - Import developer docs and CONTRIBUTING.md to docs.flagsmith.com

cursor · 2025-12-31T07:05:21Z

You have run out of free Bugbot PR reviews for this billing cycle. This will reset on January 10.

To receive reviews on all of your PRs, visit the Cursor dashboard to activate Pro and start your 14-day free trial.

vercel · 2025-12-31T07:05:23Z

The latest updates on your projects. Learn more about Vercel for GitHub.

3 Skipped Deployments

Project	Deployment	Review	Updated (UTC)
docs	Ignored	Preview	Dec 31, 2025 11:45am
flagsmith-frontend-preview	Ignored	Preview	Dec 31, 2025 11:45am
flagsmith-frontend-staging	Ignored	Preview	Dec 31, 2025 11:45am

github-actions · 2025-12-31T07:06:49Z

Docker builds report

Image	Build Status	Security report
`ghcr.io/flagsmith/flagsmith-e2e:pr-6448`	Finished ✅	Skipped
`ghcr.io/flagsmith/flagsmith-api-test:pr-6448`	Finished ✅	Skipped
`ghcr.io/flagsmith/flagsmith-e2e:pr-6448`	Finished ✅	Skipped
`ghcr.io/flagsmith/flagsmith-api-test:pr-6448`	Finished ✅	Skipped
`ghcr.io/flagsmith/flagsmith-frontend:pr-6448`	Finished ✅	Results ✅
`ghcr.io/flagsmith/flagsmith-frontend:pr-6448`	Finished ✅	Results ✅
`ghcr.io/flagsmith/flagsmith-api:pr-6448`	Finished ✅	Results ✅
`ghcr.io/flagsmith/flagsmith:pr-6448`	Finished ✅	Results ✅
`ghcr.io/flagsmith/flagsmith:pr-6448`	Finished ✅	Results ✅
`ghcr.io/flagsmith/flagsmith-private-cloud:pr-6448`	Finished ✅	Results ✅
`ghcr.io/flagsmith/flagsmith-private-cloud:pr-6448`	Finished ✅	Results ✅

codecov · 2025-12-31T07:09:42Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.06%. Comparing base (2d208b1) to head (5feac3c).
⚠️ Report is 14 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #6448   +/-   ##
=======================================
  Coverage   98.06%   98.06%           
=======================================
  Files        1292     1292           
  Lines       46509    46509           
=======================================
  Hits        45611    45611           
  Misses        898      898

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Copilot

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

docs/README.md

api/README.md

Makefile

.github/pull_request_template.md

Co-authored-by: Copilot <[email protected]>

khvn26 · 2025-12-31T11:35:20Z

frontend/README.md

I'd like to see a guide similar to api/README.md here — calling @Flagsmith/flagsmith-front-end for help.

matthewelwell

Love this! Thanks @khvn26 .

Added a few fairly minor comments.

We'll want to get feedback from @talissoncosta and @Zaimwa9 and update frontend/README.md sooner rather than later (perhaps even as part of this PR?)

api/README.md

docs/docs/project-and-community/contributing.md

docs/docs/project-and-community/development.md

Co-authored-by: Matthew Elwell <[email protected]>

Zaimwa9

A first few comments before reading the details

Zaimwa9 · 2025-12-31T12:03:01Z

CLAUDE.md

@@ -0,0 +1 @@
+Read @AGENTS.md


2 comments:

I don't know if file references works the same as when in CLI

My understanding leads me to think that having subdirectory claude.md would give us the result we want frontend/claude.md and api/claude.md for respective guidelines

Claude Code reads memories recursively: starting in the cwd, Claude Code recurses up to (but not including) the root directory / and reads any CLAUDE.md or CLAUDE.local.md files it finds. This is especially convenient when working in large repositories where you run Claude Code in foo/bar/, and have memories in both foo/CLAUDE.md and foo/bar/CLAUDE.md.

https://code.claude.com/docs/en/memory#how-claude-looks-up-memories

I'm reading everything and its opposite about the @ referencing/importing so don't trust my word. Did you have any confirmation it works ?

Did you have any confirmation in works ?

Just got Claude to generate #6451 on top of it. I did observe it correctly calling the makefile targets for backend. No idea if that confirms anything, though.

I don't know if file references works the same as when in CLI

My guess is @-style saves a bit of tokens, but I'd be happier for those to be normal markdown links, actually. It seems that AGENTS.md examples do use markdown links, so I'm leaning towards changing them.

Zaimwa9 · 2025-12-31T12:05:05Z

api/README.md

+- `mappers.py` for data mapping logic unrelated to API requests and responses.
+- `services.py` for encapsulated business logic. Our goal with this layer is to make the views, models and serialisers leaner, so that the business logic is more clearly defined and easier to compose.
+- `tasks.py` for defining asynchronous and recurring tasks.
+- `types.py` for custom type definitions, including typed dicts.


In this part we could add a couple of rules too. I'm actually thinking about the "imports at the top of the file" which is often ignored and other with naming for example (i'm not thinking about much more on the top of my mind 😄 )

I'm consciously avoiding adding guidelines that can, and should, be linter rules. Import placement/order is definitely one of those. As for naming conventions, I'd love for us to have them eventually; examples are very welcome.

This section is very deliberately incomplete, and I encourage any suggestions to expand it!

Zaimwa9 · 2025-12-31T12:09:47Z

AGENTS.md

@@ -0,0 +1,10 @@
+Prioritise @AGENTS.local.md, if present.


To me agents is working with chatgpt/codex. So we could also add the cursorrules to cover most of them

Maybe we could we have those rules in any LLM_RULES or self-explanatory name and symlink the claude.md, agents and cursorrules to it ? or as you did with agents actually, but given we are more using Claude, i would use Claude.md as the source

In Cursor docs, AGENTS.md is considered an alternative to cursorrules. Does this imply that simply having AGENTS.md is enough?

- Add AGENTS.md

d9132b3

- Add missing developer documentation - Refresh CONTRIBUTING.md - Refresh the PR template - Import developer docs and CONTRIBUTING.md to docs.flagsmith.com

khvn26 requested review from a team as code owners December 31, 2025 07:05

khvn26 requested review from Holmus and Zaimwa9 and removed request for a team December 31, 2025 07:05

github-actions bot added front-end Issue related to the React Front End Dashboard api Issue related to the REST API docs Documentation updates and removed docs Documentation updates labels Dec 31, 2025

rename api/README.md

3d7a4aa

khvn26 requested a review from Copilot December 31, 2025 07:10

github-actions bot added docs Documentation updates and removed docs Documentation updates labels Dec 31, 2025

Copilot started reviewing on behalf of khvn26 December 31, 2025 07:11 View session

khvn26 changed the title ~~docs: Add developer documentations, AGENTS.md~~ docs: Add developer documentation, AGENTS.md Dec 31, 2025

Copilot AI reviewed Dec 31, 2025

View reviewed changes

docs/README.md Outdated Show resolved Hide resolved

api/README.md Outdated Show resolved Hide resolved

Makefile Outdated Show resolved Hide resolved

.github/pull_request_template.md Show resolved Hide resolved

khvn26 and others added 3 commits December 31, 2025 11:30

fix typo

6df6fc0

Co-authored-by: Copilot <[email protected]>

fix path separators

31e3c5e

Co-authored-by: Copilot <[email protected]>

fix typo

fb75a62

Co-authored-by: Copilot <[email protected]>

github-actions bot added docs Documentation updates and removed docs Documentation updates labels Dec 31, 2025

khvn26 commented Dec 31, 2025

View reviewed changes

matthewelwell reviewed Dec 31, 2025

View reviewed changes

api/README.md Outdated Show resolved Hide resolved

api/README.md Outdated Show resolved Hide resolved

docs/docs/project-and-community/contributing.md Show resolved Hide resolved

docs/docs/project-and-community/development.md Show resolved Hide resolved

khvn26 and others added 2 commits December 31, 2025 11:45

clarify migrations squashing recommendation

30a7158

fix grammar

5feac3c

Co-authored-by: Matthew Elwell <[email protected]>

github-actions bot added docs Documentation updates and removed docs Documentation updates labels Dec 31, 2025

Zaimwa9 reviewed Dec 31, 2025

View reviewed changes

		@@ -0,0 +1 @@
		Read @AGENTS.md No newline at end of file

docs: Add developer documentation, AGENTS.md #6448

Are you sure you want to change the base?

docs: Add developer documentation, AGENTS.md #6448

Uh oh!

Conversation

khvn26 commented Dec 31, 2025

Changes

How did you test this code?

Uh oh!

cursor bot commented Dec 31, 2025

Uh oh!

vercel bot commented Dec 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Dec 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Docker builds report

Uh oh!

codecov bot commented Dec 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

matthewelwell left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Zaimwa9 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

khvn26 Dec 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

vercel bot commented Dec 31, 2025 •

edited

Loading

github-actions bot commented Dec 31, 2025 •

edited

Loading

codecov bot commented Dec 31, 2025 •

edited

Loading

khvn26 Dec 31, 2025 •

edited

Loading