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
In this repository29 other files it gives its agents.
- ark/CLAUDE.mdCLAUDE.md
- tests/CLAUDE.mdCLAUDE.md
- a2a-protocolSkill
- Ark AnalysisSkill
- ark-architectureSkill
- ark-controller-developmentSkill
- ark-dependabot-managementSkill
- ark-sdk-developmentSkill
- ark-setup-clusterSkill
- ark-chainsaw-testingSkill
- Ark Dashboard and UI TestingSkill
- ark-documentationSkill
- issue-creationSkill
- ark-issuesSkill
- multi-branch-cluster-setupSkill
- openspec-apply-changeSkill
- openspec-archive-changeSkill
- openspec-bulk-archive-changeSkill
- openspec-continue-changeSkill
- openspec-exploreSkill
- openspec-ff-changeSkill
- openspec-new-changeSkill
- openspec-onboardSkill
- openspec-sync-specsSkill
- openspec-verify-changeSkill
- ark-pentest-issue-resolverSkill
- ark-researchSkill
- slack-announcementSkill
- ark-vulnerability-fixerSkill
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
- Very specific: line 7
BEFORE pushing ANY commit, make lint and make test MUST pass locally in every directory the change touches.
- Distinctive: line 79
All Go services follow this pattern:
- Very specific: line 88
All Python services use uv and follow this pattern:
- Distinctive: line 140
Be concise and direct: - Remove unnecessary adjectives and verbose descriptions
- Distinctive: line 141
Use simple language: - Avoid complex explanations when simple ones work
- Distinctive: line 142
State facts clearly: - Don't embellish with "comprehensive", "advanced", "sophisticated"
- Distinctive: line 146
Ark capitalization: - Always write "Ark" (capital A, lowercase rk), never "ARK" in documentation
- Distinctive: line 159
if there are no steps required, simply touch the appropriate stamp file
- Very specific: line 160
All phony targets should depend on a STAMP_SERVICE_<TARGET> that is put in $(OUT)/<SERVICE> directory
- Distinctive: line 166
When a service depends on another service's stamp file (e.g., ark-api depends on localhost-gateway), use double-dollar syntax for deferred …
- Distinctive: line 240
When creating pull requests, use this simple format:
- Distinctive: line 246
DO NOT include "Test plan" sections in PR descriptions.
- Distinctive: line 256
When adding commits to an existing PR that expand beyond the original scope:
≈ “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.
Files
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+gofumptfor Go,ruff/pyrightfor Python,eslintfor 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
gofumptand whitespace diffs the most. Run the gates regardless of change size. - Tooling gotcha (Go):
GOLANGCI_LINT_VERSIONinark/Makefilemay lag local Go. Ifmake linterrors with "Go language version ... used to build golangci-lint is lower than the targeted Go version", fall back togofumpt -l .(install viago install mvdan.cc/gofumpt@latest) — this catches the formatting rule that breaks CI most often. Fullgolangci-lintstill 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
BaseExecutorABC andExecutorApp(A2A bridge) provide the standard interface for pluggable executors- Downstream executor implementations live in the marketplace
services/- Component servicesark-api/- REST API gateway (Python/FastAPI) with streaming, A2A, broker integrationark-broker/- In-memory event bus (Node.js/Express) for messages, chunks, traces, events, sessionsark-dashboard/- Web UI (Next.js/React)ark-mcp/- MCP server host servicelocalhost-gateway/- Local development gateway
samples/- Example YAML configurations for agents, models, queries, teamsdocs/- Documentation site (Next.js/MDX)
Supporting Folders
tools/- CLI toolsark-cli/- Ark CLI (Node.js) - General-purpose, interactivefark/- Fark CLI (Go) - Optimized for resource management and low latency
bundles/- Component bundles and manifestsscripts/- Build and deployment scripts (Bash)templates/- Project templates for new services
Build Instructions
Root Commands
devspace dev- Deploy ARK to your clustermake docs- Run documentation site with live-reloadmake 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 modeGo 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 imagePython 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 containerNode.js Services
cd docs/ # Documentation site
npm build # Build siteObservability
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/phoenixCLI 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/binWriting 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 devExamples 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 itBuild & 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 changesDO NOT include "Test plan" sections in PR descriptions.
Environment Variable Naming
Duration env vars must include a unit suffix:
_MSfor milliseconds (e.g.,REQUEST_TIMEOUT_MS)_SECONDSfor seconds (e.g.,ARK_MEMORY_HTTP_TIMEOUT_SECONDS)
Pull Request Maintenance
When adding commits to an existing PR that expand beyond the original scope:
- Update PR title to reflect the broader changes using conventional commit format
- Update PR description to summarize all changes, not just the original ones
- Use
gh pr editto 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"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
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.

