docs: add CLAUDE.md files for AI-assisted development

[tylerbutler]

Summary

• Adds 163 CLAUDE.md documentation files throughout the Fluid Framework monorepo
• Root-level file provides workspace overview: build system, commands, structure, code style, testing conventions
• Package-specific files document build/test/lint commands, key files, API exports, and notable dependencies

Coverage

• Core packages: DDSs, drivers, framework, loader, runtime, service-clients
• Experimental packages including PropertyDDS
• Examples: apps, benchmarks, data-objects, service-clients, utilities, view-integration
• Tools: devtools suite, fluid-runner, fetch-tool, replay-tool, markdown-magic
• Common/build: eslint-config-fluid
• Azure packages: local-service, service-utils

These files enable AI assistants to understand package structure and available commands when working within specific packages.

[Copilot]

Pull request overview

This PR adds 163 CLAUDE.md documentation files throughout the Fluid Framework monorepo to improve AI-assisted development. The root-level file provides workspace overview covering build system, commands, structure, code style, and testing conventions. Package-specific files document build/test/lint commands, key files, API exports, and notable dependencies across core packages (DDSs, drivers, framework, loader, runtime, service-clients), experimental packages including PropertyDDS, examples (apps, benchmarks, data-objects, service-clients, utilities, view-integration), tools (devtools suite, fluid-runner, fetch-tool, replay-tool, markdown-magic), common/build (eslint-config-fluid), and Azure packages (local-service, service-utils).

Reviewed changes

Copilot reviewed 163 out of 163 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
CLAUDE.md	Root-level workspace documentation with build system, commands, structure overview
tools/markdown-magic/CLAUDE.md	Documentation for markdown content generation tool
packages/utils/*/CLAUDE.md	Utility packages documentation (tool-utils, telemetry-utils, odsp-doclib-utils)
packages/tools/*/CLAUDE.md	Developer tools documentation (replay-tool, fluid-runner, fetch-tool, devtools/*)
packages/test/*/CLAUDE.md	Test utilities and infrastructure documentation
packages/service-clients/*/CLAUDE.md	Service client implementations documentation
packages/runtime/*/CLAUDE.md	Runtime component documentation
packages/framework/*/CLAUDE.md	Framework packages documentation
packages/drivers/*/CLAUDE.md	Driver implementations documentation
packages/dds/*/CLAUDE.md	Distributed Data Structures documentation
packages/common/*/CLAUDE.md	Common interfaces and utilities documentation
experimental/*/CLAUDE.md	Experimental packages documentation
examples/*/CLAUDE.md	Example applications documentation
azure/packages/*/CLAUDE.md	Azure-specific packages documentation
common/build/eslint-config-fluid/CLAUDE.md	ESLint configuration documentation

The documentation appears comprehensive, well-structured, and consistent across all files. No critical issues were found during the review.

[github-actions]

🔗 No broken links found! ✅

Your attention to detail is admirable.

linkcheck output

> fluid-framework-docs-site@0.0.0 ci:check-links /home/runner/work/FluidFramework/FluidFramework/docs
> start-server-and-test "npm run serve -- --no-open" 3000 check-links

1: starting server using command "npm run serve -- --no-open"
and when url "[ 'http://127.0.0.1:3000' ]" is responding with HTTP status code 200
running tests using command "npm run check-links"


> fluid-framework-docs-site@0.0.0 serve
> docusaurus serve --no-open

[SUCCESS] Serving "build" directory at: http://localhost:3000/

> fluid-framework-docs-site@0.0.0 check-links
> linkcheck http://localhost:3000 --skip-file skipped-urls.txt

Crawling...

Stats:
  245432 links
    1786 destination URLs
    2025 URLs ignored
       0 warnings
       0 errors

[tylerbutler]

proper command is just pnpm build <package-name>

[anthony-murphy]

in the past I've had problems with any kind of instruction files existing, and it having a very negative impact on model output quality. I think it just ends up polluting the context with a bunch of additional instructions which can confused the model. is there any way to keep this personal, rather that checked in globally?

[tylerbutler]

in the past I've had problems with any kind of instruction files existing, and it having a very negative impact on model output quality. I think it just ends up polluting the context with a bunch of additional instructions which can confused the model. is there any way to keep this personal, rather that checked in globally?

Yeah, we could add gitignore entries so folks could keep the files locally without polluting the repo.

That said, I don't think files like this are that valuable unless they're shared/kept updated, which is hard to do without checking them in. My experience has been that they're more helpful with Claude code than other agents, but it's all anecdotal.

[anthony-murphy]

in the past I've had problems with any kind of instruction files existing, and it having a very negative impact on model output quality. I think it just ends up polluting the context with a bunch of additional instructions which can confused the model. is there any way to keep this personal, rather that checked in globally?

Yeah, we could add gitignore entries so folks could keep the files locally without polluting the repo.

That said, I don't think files like this are that valuable unless they're shared/kept updated, which is hard to do without checking them in. My experience has been that they're more helpful with Claude code than other agents, but it's all anecdotal.

yeah. its hard. i'd like everyone to be able to experiment which includes sharing and not sharing, as it really hard to understand why sometimes results are good, and other times they are not.

i use the Claude model a lot, mainly with copilot, and find the less prompt the better, but it could just be how i prompt, or what i consider good for the problem I'm working on.

i wonder if we can get the best of both worlds somehow. my first though is

1. check them in somewhere
2. ignore them by default in the code
3. have script to distribute them, maybe by default based on some environment variable
4. could also support multiple sets, per dev, per scenario

i would have claude build this infra.

[tylerbutler]

i use the Claude model a lot, mainly with copilot, and find the less prompt the better,

I have also found that to be true when using copilot with the Claude model - but not with Claude Code itself. There appears to be more to it than just the model.

[anthony-murphy]

i use the Claude model a lot, mainly with copilot, and find the less prompt the better,

I have also found that to be true when using copilot with the Claude model - but not with Claude Code itself. There appears to be more to it than just the model.

i'd really like to keep the ability to experiment, but i don't have a good solution. if you don't want to do more, could we minimize this, and only add one at the root, rather than one per package so local modification is easier

[anthony-murphy]

so far i haven't found these types of instructions to be necessary. if i point claude cli at the code base it installs, builds, and tests just fine without specific instruction. Are you seeing specific problems in these areas that you are trying to resolve?