docs: package-level CLAUDE.md across the monorepo#1711
Open
Scra3 wants to merge 5 commits into
Open
Conversation
Tighten the architecture-principles prose into scannable invariants, refresh the package map (add mcp/factory/agent-with-log/record-step-executor), and add practical context: step types & execution modes, Node >=22.12 + single-test commands, and gotchas (stale cross-package build cache, hard-to-run e2e, SQLite/pg test gating). Kept all hard-won invariants. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
Coverage Impact ⬇️ Merging this pull request will decrease total coverage on 🛟 Help
|
Generate a concise, package-specific CLAUDE.md for every package that lacked one (19 packages: agent, agent-client, agent-testing, agent-toolkit, the datasource-* family, forest-cloud, forestadmin-client, mcp-server, plugin-*). Each captures the package's role, the big-picture architecture that needs reading multiple files, workspace-scoped commands + single-test, and the package-specific gotchas — without duplicating the root CLAUDE.md. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Scra3
changed the title
![macroscopeapp[bot]](https://avatars.githubusercontent.com/in/900172?s=60&v=4){kind=small}
Rewrite the existing ai-proxy CLAUDE.md to match the standard format used across the monorepo: overview + architecture (OpenAI-wire proxy, provider dispatch, remote tools/integrations, Router discriminated union), commands, and package gotchas. Adversarially verified against the source. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Reviewed every package CLAUDE.md against its source (one reviewer per file). 5 were clean; 16 had real inaccuracies, now corrected & re-verified, notably: - workflow-executor: AI types come from @forestadmin/ai-proxy (not @langchain/core, which isn't a dependency); corrected the full Trigger Action AI-fill flow. - agent-client: CollectionChart does not extend Chart (distinct chart endpoints). - forestadmin-client: permissions match raw action ids; only charts are hashed. - mcp-server / forest-cloud / datasource-mongo / datasource-sql: wrong single-test paths (tests live under test/, not src/). - ai-proxy: added the AiClient surface (used by workflow-executor); error-import package. - agent / agent-testing / datasource-* : assorted flow/handle/fixture corrections. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Flattening and write handlers are mutually exclusive: WriteDataSourceDecorator throws at construction if any flattenOptions coexist with a write handler — not "writes work on root collections, disabled on sub-models". Fixes the macroscope review finding. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds a concise, package-specific
CLAUDE.mdto every package so future Claude Code sessions get the right context per package, plus a rewrite of the existing workflow-executor one.What's in here
agent,agent-client,agent-testing,agent-toolkit, thedatasource-*family (customizer, toolkit, sql, sequelize, mongo, mongoose, replica, dummy, demo-fintech),forest-cloud,forestadmin-client,mcp-server,plugin-aws-s3,plugin-export-advanced,plugin-flattener.Conventions
CLAUDE.md. Grounded in actual code, verified against currentmain.Not touched:
_example(demo app, local WIP),ai-proxy(already had one).🤖 Generated with Claude Code
Note
Add package-level CLAUDE.md documentation across the monorepo
Adds or rewrites
CLAUDE.mdguidance files for 20+ packages in the monorepo, giving Claude Code package-specific context for each area of the codebase. Each file covers overview, architecture, key entry points, CLI commands, and package-specific gotchas. More detailed packages (e.g.workflow-executor,ai-proxy,datasource-sql) include invariants, error hierarchies, idempotency schemes, and known edge cases.Macroscope summarized bfafc7f.