[DISCUSS] What should the repository tell coding agents, and where?

[Astro-Han]

Why now

Three threads each answer part of this and none can move without the others:

• docs: add AGENTS.md #3576 adds a root AGENTS.md (with CLAUDE.md as a symlink). It is accurate, and it is parked because a root instruction file is not documentation people choose to read: buildWorkspaceInstructionsPromptFragment injects it into the system prompt of every agent session whose cwd is this repository, which makes it a change to every contributor's agent, not a docs change.
• Adopt Storybook's official MCP addon to give agents a queryable component interface #3527 proposes @storybook/addon-mcp so an agent can list components and read props before writing UI.
• The design system we build on ships its own agent workflow (Astryx "working with AI"): npx @astryxdesign/cli init --features agents generates agent rules, and https://astryx.atmeta.com/mcp serves its docs. The CLI is already pinned in package.json; none of the workflow is wired.

The cost of leaving this open is visible: three CSS dialects across 67 stylesheets, 13 of 14 settings pages on the stacked-card structure Astryx documents as an anti-pattern, product CSS re-authoring chrome Astryx owns. Each agent reinvents the dialect because the repo never states it in a form agents read.

Proposal

1. Root AGENTS.md (from docs: add AGENTS.md #3576) carries only what every session needs: layout, commands, test and lint gates, PR conventions. Nothing surface-specific. CLAUDE.md stays a symlink so there is one copy.
2. Nested apps/desktop/AGENTS.md and packages/ui/AGENTS.md carry the frontend rules, generated by npx @astryxdesign/cli init --features agents --agent-docs-path <path> and edited to defer to DESIGN.md and docs/frontend-css-governance.md for every Maka-specific rule. Nested files load only when an agent works in that tree, so runtime and CLI sessions never see them.
3. One tracked .mcp.json with two entries: the Storybook addon from Adopt Storybook's official MCP addon to give agents a queryable component interface #3527 and Astryx's xds. Agents that support MCP pick them up; others lose nothing.
4. DESIGN.md remains the single Maka design authority. The generated files may restate Astryx's own rules; they do not restate Maka's.

What changes for contributors

Every agent session in this repo loads the root file; frontend sessions load one nested file and, where the tool supports MCP, gain two docs servers. Lint, CI and review requirements do not change. Contributors who do not use agents are unaffected.

Open questions

• Is a tracked .mcp.json acceptable given it names external and local servers, or should it be documented in CONTRIBUTING.md and left opt-in?
• Should the root file be reviewed like code (any change needs a PR with a stated reason), since it changes agent behaviour repo-wide?
• Size: docs: add AGENTS.md #3576 is 13 KB. Is that the ceiling for the root, with everything else pushed to nested files and links?

If this converges, #3576 proceeds as the root file, #3527 and the Astryx items land as one follow-up PR, and the Desktop tracker #4679 picks up the frontend rules item.

Related: #4156 (local validation hooks by default), #4369 (npm → pnpm).

[chinawch007]

My view is as follows:

1. I think .mcp.json should be tracked in the repository.

   Compared with documenting MCP endpoints only in CONTRIBUTING.md, .mcp.json gives clients that support repository-scoped MCP configuration a machine-readable and reproducible discovery mechanism. This provides a more systematic and effective way for contributors to use Storybook and other MCP servers approved by the project.

   CONTRIBUTING.md should still document how to start local services, their intended scope, known limitations, and troubleshooting steps, but prose documentation is not a complete substitute for machine-readable configuration. Because .mcp.json affects supporting Agent clients, additions, removals, and endpoint changes for both local and remote servers should receive normal repository review. The file should contain no credentials, and client-side trust and permission controls should continue to apply.

2. If the project adopts a root AGENTS.md, I think it should be reviewed with the same care as code.

   A root instruction file affects every Agent session whose working directory is this repository, so changing it is more than an ordinary documentation edit. Each change should go through a PR, explain its motivation and expected behavioral impact, and be reviewed for accuracy, necessity, repository-wide applicability, and possible conflicts with more specific nested instructions.

3. I would not make 13 KB the root-file ceiling merely because the currently unmerged #3576 happens to be approximately that size.

   The root AGENTS.md is loaded into every Agent session, so it should remain concise and contain only information that is genuinely repository-wide and needed in every session. Frontend-specific and other domain-specific guidance should be moved into the relevant nested files or referenced for on-demand reading.

   For comparison, Codex defaults project_doc_max_bytes to 32 KiB. This is a combined budget for project instructions loaded along the path from the repository root to the current working directory; see the official Codex documentation. apps/desktop/AGENTS.md and packages/ui/AGENTS.md are sibling files and therefore would not normally be loaded together for one working directory, but each relevant nested file still shares the 32 KiB budget with the root file. A 13 KB root file would consume roughly 40% of that default budget in every session before any relevant nested guidance is added, so reducing it would still be worthwhile.

   Maka itself currently has stricter fixed limits:

   • MAX_WORKSPACE_INSTRUCTION_FILE_CHARS = 6000, limiting each workspace instruction file to 6,000 characters; and
   • MAX_WORKSPACE_INSTRUCTIONS_PROMPT_CHARS = 14000, limiting the combined rendered workspace-instruction fragment, including its wrapper text, to approximately 14,000 characters.

   Consequently, when using Maka to work on Maka itself, the proposed English root AGENTS.md of approximately 13 KB would be truncated at about 6,000 characters and would not be loaded in full.

   I could not find a documented derivation for these two Maka constants—based on model context windows, token budgets, or evaluation results—in the introducing commit, code comments, or tests. They appear to be fixed safety guardrails rather than final empirically derived limits. We can revisit them in a separate issue using the context windows of the models Maka supports, measured token usage across different languages, and relevant evaluations.

中文

我的看法如下：

1. 我认为 .mcp.json 应当纳入版本控制。

   相比只在 CONTRIBUTING.md 中描述 MCP endpoint，.mcp.json 为支持仓库级 MCP 配置的客户端提供了一种机器可读、可复现的发现机制。这可以更系统、有效地帮助贡献者使用 Storybook 以及其他经过项目认可的 MCP server。

   CONTRIBUTING.md 仍然应该保留，用于说明本地服务的启动方式、适用范围、已知限制和故障排查，但它不能完全替代机器可读的配置。由于 .mcp.json 会影响支持它的 Agent 客户端，其中本地和远程 server 的任何增删或 endpoint 变更都应当像其他仓库配置一样接受评审。该文件不应包含凭据，客户端自身的信任和权限机制也仍然适用。

2. 如果项目决定采用根 AGENTS.md，我认为它应当像代码一样被评审。

   根指令文件会影响以该仓库为工作目录的所有 Agent 会话，因此对它的修改不只是普通文档编辑。每项变更都应通过 PR，说明修改原因及预期行为影响，并仔细检查指令是否准确、必要、适用于整个仓库，以及是否会与更具体的嵌套指令发生冲突。

3. 我不建议仅仅因为尚未合入的 #3576 当前约为 13 KB，就把 13 KB 直接定义为根文件的上限。

   根 AGENTS.md 会进入每个 Agent 会话，因此应该尽量精简，只保留真正适用于整个仓库、且每个会话都需要知道的内容。前端或其他特定领域的规则应当放入相应的嵌套文件，或者通过链接按需引用。

   作为参考，Codex 的 project_doc_max_bytes 默认值为 32 KiB，限制的是从项目根目录到当前工作目录这条路径上所加载项目指令的合计大小，详见 Codex 官方文档。apps/desktop/AGENTS.md 和 packages/ui/AGENTS.md 作为 sibling 文件通常不会在同一工作目录下同时加载，但每个相关的嵌套文件都需要与根文件共享这 32 KiB 预算。一个 13 KB 的根文件本身就会在每次会话中消耗约 40% 的默认预算，因此仍然值得精简。

   Maka 自身目前也设置了更严格的固定限制：

   • MAX_WORKSPACE_INSTRUCTION_FILE_CHARS = 6000：每个 workspace instruction 文件最多加载 6,000 个字符；
   • MAX_WORKSPACE_INSTRUCTIONS_PROMPT_CHARS = 14000：所有此类文件及其包装文本合计最多约 14,000 个字符。

   因此，如果使用 Maka 来开发 Maka，当前这份约 13 KB 的英文根 AGENTS.md 会在大约 6,000 个字符处被截断，无法完整加载。

   我没有在最初引入这两个 Maka 常量的提交、代码注释或测试中找到基于模型上下文窗口、token 预算或评测结果的推导依据。它们看起来更像固定的安全保护值，而不是经过测量得到的最终标准。我们可以在后续独立 issue 中，根据 Maka 支持模型的 context window、不同语言的实际 token 消耗以及相关 eval 结果重新评估它们。

AI assistance disclosure: I drafted this response, used AI assistance for review, and take full responsibility for its content.