agentleFS
mckinseymckinsey/agents-at-scale-ark/CLAUDE.md

agents-at-scale-ark

CLAUDE.md438 starsChanged 7 months agoApache-2.0View on GitHub

NEVER add comments to generated code unless explicitly requested by the user BEFORE pushing ANY commit, make lint and make test MUST pass locally in every directory the change touches. Exact commands per stack live in "Build Instructions" below; do not skip them. - Never push with lint failures. Same rules CI enforces (golangci-lint + gofumpt for Go, ruff/pyright for Python, eslint for TypeScript). Local pass is the minimum bar. - Never push with failing tests. - Never bypass hooks…

  • Installs packages

The file

Show its rules and text

We split this CLAUDE.md into the rules it gives an agent

13 rules. About 0 are common, 10 are distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈10

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    BEFORE pushing ANY commit, make lint and make test MUST pass locally in every directory the change touches.

    line 7
  2. Distinctive:

    All Go services follow this pattern:

    line 79
  3. Very specific:

    All Python services use uv and follow this pattern:

    line 88
  4. Distinctive:

    Be concise and direct: - Remove unnecessary adjectives and verbose descriptions

    line 140
  5. Distinctive:

    Use simple language: - Avoid complex explanations when simple ones work

    line 141
  6. Distinctive:

    State facts clearly: - Don't embellish with "comprehensive", "advanced", "sophisticated"

    line 142
  7. Distinctive:

    Ark capitalization: - Always write "Ark" (capital A, lowercase rk), never "ARK" in documentation

    line 146
  8. Distinctive:

    if there are no steps required, simply touch the appropriate stamp file

    line 159
  9. Very specific:

    All phony targets should depend on a STAMP_SERVICE_<TARGET> that is put in $(OUT)/<SERVICE> directory

    line 160
  10. Distinctive:

    When a service depends on another service's stamp file (e.g., ark-api depends on localhost-gateway), use double-dollar syntax for deferred …

    line 166
  11. Distinctive:

    When creating pull requests, use this simple format:

    line 240
  12. Distinctive:

    DO NOT include "Test plan" sections in PR descriptions.

    line 246
  13. Distinctive:

    When adding commits to an existing PR that expand beyond the original scope:

    line 256

≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

CLAUDE.md

NEVER add comments to generated code unless explicitly requested by the user

Pre-Push Gates (Non-Negotiable)

BEFORE pushing ANY commit, make lint and make test MUST pass locally in every directory the change touches. Exact commands per stack live in "Build Instructions" below; do not skip them.

  • Never push with lint failures. Same rules CI enforces (golangci-lint + gofumpt for Go, ruff/pyright for Python, eslint for TypeScript). Local pass is the minimum bar.
  • Never push with failing tests.
  • Never bypass hooks (--no-verify, --no-gpg-sign) unless the user explicitly asks.
  • "One-line changes" hide gofumpt and whitespace diffs the most. Run the gates regardless of change size.
  • Tooling gotcha (Go): GOLANGCI_LINT_VERSION in ark/Makefile may lag local Go. If make lint errors with "Go language version ... used to build golangci-lint is lower than the targeted Go version", fall back to gofumpt -l . (install via go install mvdan.cc/gofumpt@latest) — this catches the formatting rule that breaks CI most often. Full golangci-lint still runs in CI.

Project Structure

Core Folders

  • ark/ - Kubernetes operator (Go)
    • Controller reconciles CRDs: Agent, Model, Query, Team, MCPServer, ExecutionEngine, A2AServer
    • Webhooks for validation and mutation (including migration warnings)
    • executors/completions/ - Default executor (separate deployment, communicates with controller via A2A)
    • The controller dispatches queries to the appropriate executor via A2A protocol
  • lib/ark-sdk/ - Python SDK (generated + overlay)
    • Generated from CRDs via OpenAPI, with hand-written overlay for executor interfaces
    • BaseExecutor ABC and ExecutorApp (A2A bridge) provide the standard interface for pluggable executors
    • Downstream executor implementations live in the marketplace
  • services/ - Component services
    • ark-api/ - REST API gateway (Python/FastAPI) with streaming, A2A, broker integration
    • ark-broker/ - In-memory event bus (Node.js/Express) for messages, chunks, traces, events, sessions
    • ark-dashboard/ - Web UI (Next.js/React)
    • ark-mcp/ - MCP server host service
    • localhost-gateway/ - Local development gateway
  • samples/ - Example YAML configurations for agents, models, queries, teams
  • docs/ - Documentation site (Next.js/MDX)

Supporting Folders

  • tools/ - CLI tools
    • ark-cli/ - Ark CLI (Node.js) - General-purpose, interactive
    • fark/ - Fark CLI (Go) - Optimized for resource management and low latency
  • bundles/ - Component bundles and manifests
  • scripts/ - Build and deployment scripts (Bash)
  • templates/ - Project templates for new services

Build Instructions

Root Commands

  • devspace dev - Deploy ARK to your cluster
  • make docs - Run documentation site with live-reload
  • make services - Install and configure additional service capabilities

Ark Controller (Go)

cd ark/
make build         # Build manager binary
make test          # Run tests with coverage
make docker-build  # Build Docker image
make deploy        # Deploy to K8s cluster
make dev           # Run in development mode

Go Services

All Go services follow this pattern:

cd services/{service-name}/
make build-binary  # Build Go binary locally
make test          # Run tests
make build         # Build Docker image

Python Services

All Python services use uv and follow this pattern:

cd services/{service-name}/
make init          # Install dependencies (uv sync)
make dev           # Run locally (uv run python -m {module})
make test          # Run tests with coverage
make lint          # Run linting and type checking
make build         # Build container

Node.js Services

cd docs/           # Documentation site
npm build          # Build site

Observability

Ark uses OpenTelemetry with W3C TraceContext and Baggage propagation for distributed tracing. The operator instruments query dispatch and A2A communication, automatically propagating trace context to downstream executors via HTTP headers. The telemetry subsystem lives in ark/internal/telemetry/, and the ExecutorApp base class in lib/ark-sdk/ handles context extraction on the executor side.

Marketplace

Ark has a separate marketplace repository for add-on components that extend Ark's native capabilities. Marketplace items depend on Ark core — never the other way around.

Repository: https://github.com/mckinsey/agents-at-scale-marketplace

The marketplace includes executors (Claude Agent SDK, LangChain), services (Phoenix, Langfuse, ark-sandbox, file-gateway), MCP servers, pre-built agents, and demo bundles. Components can be deployed using DevSpace or Helm as dependencies of your Ark installation.

Example usage in devspace.yaml:

dependencies:
  phoenix:
    git: https://github.com/mckinsey/agents-at-scale-marketplace
    tag: v0.1.1
    subPath: services/phoenix

CLI Tools

cd tools/ark-cli/  # Ark CLI (Node.js)
npm install        # Install dependencies
npm run build      # Build TypeScript
npm test           # Run tests

cd tools/fark/     # Fark CLI (Go)
make build-binary  # Build binary
make test          # Run tests
make install       # Install to ~/.local/bin

Writing Style

  • Be concise and direct - Remove unnecessary adjectives and verbose descriptions
  • Use simple language - Avoid complex explanations when simple ones work
  • State facts clearly - Don't embellish with "comprehensive", "advanced", "sophisticated"
  • Keep descriptions brief - 1-2 sentences maximum for each item
  • Use active voice - "Creates agent" not "Agent is created"
  • Avoid extra adjectives
  • Ark capitalization - Always write "Ark" (capital A, lowercase rk), never "ARK" in documentation

Makefile Guidelines

  • The top level Makefile will always include child fragments, such as lib/lib.mk and service/service.mk
    • anything needing $(OUT) will include it as a dependency like: | $(OUT)
    • the top level makefile will define a PHONY target named clean, which removes $(OUT), and any directory/file add to a CLEAN_TARGET list variable
  • helpers.mk at the root incldues all variables and lists
    • the OUT variable is defined before all incudes in the root makefile, it is assigned to abspath/out
    • an $(OUT) target will create the $(OUT) directory in the helpers.mk makefile
    • helpers.mk enables .SECONDEXPANSION: for cross-service dependencies
  • The child fragments will include grandchildren, such as service/service.mk including service/ark-dashboard/build.mk
  • Each grandchild fragment should include <SERVICE>-build, <SERVICE>-install, <SERVICE>-uninstall, <SERVICE>-test and <SERVICE>-dev phony targets
    • if there are no steps required, simply touch the appropriate stamp file
  • All phony targets should depend on a STAMP_SERVICE_<TARGET> that is put in $(OUT)/<SERVICE> directory
  • Where possible, depend on STAMP_SERVICE_<build> targets instead of doing a make in a subdir
  • Where possible, ensure the make is parallelizable

Cross-Service Dependencies

When a service depends on another service's stamp file (e.g., ark-api depends on localhost-gateway), use double-dollar syntax for deferred expansion:

# Correct - uses secondary expansion
$(ARK_API_STAMP_INSTALL): $(ARK_API_STAMP_BUILD) $$(LOCALHOST_GATEWAY_STAMP_INSTALL)

# Wrong - variable may not be defined yet
$(ARK_API_STAMP_INSTALL): $(ARK_API_STAMP_BUILD) $(LOCALHOST_GATEWAY_STAMP_INSTALL)

This ensures the dependency is resolved after all makefiles are included, preventing issues with include order.

README Guidelines

READMEs should be terse and focus only on developer setup:

Heading

Title. 2-3 lines on what the project is for..

Quickstart

The absolute basics. We always use a Makefile which supports help. The quickstart should typically include a snippet like this:

# Show all available recipes.
make help

# Install/uninstall - sets up your local machine or cluster.
make install
make uninstall

# Run in development mode. May require extra tools and setup, check the README.
make dev

Examples of Good vs Bad Documentation

Bad (verbose):

This comprehensive example demonstrates the sophisticated capabilities of our advanced weather forecasting system with multiple tool chaining workflows.

Good (concise):

Weather forecasting with tool chaining.

Bad (unclear):

Leverages the powerful Model Context Protocol for extensible external service integration capabilities.

Good (clear):

Uses MCP for external service integration.

Sample Documentation Pattern

For each sample file, use this structure:

#### `filename.yaml` - Brief Title
One sentence description.
- **Resource**: What it creates
- **Use case**: When to use it

Build & CI/CD

For build failures, CI issues, CVEs, dependabot management, and test failures, use the ark-build-manager agent. It triages failures across workflow runs and delegates to appropriate skills (chainsaw, vulnerability-fixer, ark-dependabot-management, etc.).

Testing Guidelines

When writing tests for any service, consult tests/CLAUDE.md for comprehensive testing patterns and best practices. That guide covers Chainsaw e2e tests; for a service's own unit tests, also check that service's CLAUDE.md — services/ark-dashboard/CLAUDE.md in particular carries conventions a dashboard change will otherwise miss.

Commit and PR Requirements

CRITICAL: All commit messages and PR titles MUST follow conventional commit format (e.g., feat:, fix:, docs:, chore:). This is required for automated release management with Release Please. Non-conventional commits will block PR merges.

Pull Request Format

When creating pull requests, use this simple format:

## Summary
- Brief description of changes

DO NOT include "Test plan" sections in PR descriptions.

Environment Variable Naming

Duration env vars must include a unit suffix:

  • _MS for milliseconds (e.g., REQUEST_TIMEOUT_MS)
  • _SECONDS for seconds (e.g., ARK_MEMORY_HTTP_TIMEOUT_SECONDS)

Pull Request Maintenance

When adding commits to an existing PR that expand beyond the original scope:

  1. Update PR title to reflect the broader changes using conventional commit format
  2. Update PR description to summarize all changes, not just the original ones
  3. Use gh pr edit to update title and body efficiently

Example:

# Original: "fix: increase test timeouts"
# Updated: "fix: improve CI/CD reliability and container registry configuration"
gh pr edit --title "fix: improve CI/CD reliability and container registry configuration" --body "## Summary
- Increase chainsaw test timeouts for LLM operations
- Fix container registry paths to include repository name for GHCR access control  
- Add NPM package metadata for proper display on npmjs.com
- Fix deploy workflow parameter naming"

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.