project: add a CLAUDE.md file (Bug 2015621)

[cgsheeh]

Add a CLAUDE.md file which outlines some basic details
of working in the Lando project, including some code
conventions and general layout of the project. We can
start with this as a baseline and iterate on it as
needed.

[github-actions]

View this pull request in Lando to land it once approved.

[shtrom]

r+ w/ nit re: type hint

[shtrom]

nits:

Suggested change

	- Always add assert messages in tests: `assert a == b, "a and b should be equal"`. Where possible, comments surrounding assert statements should instead become assert messages.
	- Type-hint function arguments and return values
	- Always add assert messages in tests: `assert a == b, "a and b should be equal"`. Where possible, comments surrounding assert statements should instead become assert messages.

[cgsheeh]

We use ruff to enforce ANN rules, so the agent will see test and formatting failures for type hints anyways. I added a note about this, and suggested that the agent should use specific types as much as possible (ie don't use str | int as a type, just pick one of str or int).

[zzzeid]

I would suggest removing all references to package versions, it doesn't seem necessary and could be a pain to keep up to date.

[zzzeid]

Seems like the content of this file could be useful as a general overview of Lando for anyone who wants to learn more about how it works. I don't think we should make it specific for consumption by bots.

[shtrom]

We could rename the file to CONTRIBUTING.md, and just add an @CONTRIBUTING.md to CLAUDE.md. Firefox does something in this ilk https://searchfox.org/firefox-main/source/CLAUDE.md.

[zzzeid]

Can you add more context to the bug as well, as to why we are adding this file? Is there an integration that's going to depend on this?

I would rename this to a more generic explainer and maybe tell that integration to point to that instead.

There's also duplication of info between this and the README so maybe we should just update the README with more comprehensive info.

[cgsheeh]

Can you add more context to the bug as well, as to why we are adding this file? Is there an integration that's going to depend on this?

It's in the file at the very top: "This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository."

Essentially when you run claude from the root of this repo, the first thing it will do it read this file into the model's context. This allows the agent to start working with a basic understanding of the project without having to be repeatedly instructed or steered in the right direction.

Here are the Firefox AGENTS.md/CLAUDE.md files, and Mana has some details on CLAUDE.md as well

I would rename this to a more generic explainer and maybe tell that integration to point to that instead.

There's also duplication of info between this and the README so maybe we should just update the README with more comprehensive info.

Good call. I moved much of the content to the README and made this file reference the README.

[cgsheeh]

I would suggest removing all references to package versions, it doesn't seem necessary and could be a pain to keep up to date.

I changed these to instead include a reference to the file where the version can be found.

[zzzeid]

Good call. I moved much of the content to the README and made this file reference the README.

Is claude or any other similar tool unable to detect the README itself (i.e., this universally accepted naming convention for a file that should give you the information you need about something)? Or on a per-session or use basis, can the README file be specified for the source of this information? This new file seems redundant/unnecessary.

The README additions themselves are good though but I think the language could be updated to be a little less mechanical.

[cgsheeh]

Is claude or any other similar tool unable to detect the README itself (i.e., this universally accepted naming convention for a file that should give you the information you need about something)?

CLAUDE.md is automatically injected into claude's context. Claude could read the README, but it would have to decide to based on a prompt. It may decide to read that file, it may not read it, or it may read it and read many other unnecessary files which pollute the context. Think of this like a repo-level config file for a tool, similar to compose.yaml or .gitignore.

Or on a per-session or use basis, can the README file be specified for the source of this information? This new file seems redundant/unnecessary.
The README additions themselves are good though but I think the language could be updated to be a little less mechanical.

The file is currently only 3 lines, and it's mostly just a "pointer" to the README. The actual substance are the README improvements. Over time, CLAUDE.md may diverge from the readme as it contains more mechanical language and instructions on specific behaviours for the AI to take.