Architecture contracts with agents

Use CloudArch to define module responsibilities, public entrypoints and allowed dependencies. Save that architecture as a contract in Git, give Codex or Claude Code a task brief from it, and check the resulting JavaScript or TypeScript imports. When code violates a boundary, the report identifies the file, line and module connection to inspect.

The architecture CLI and its local MCP server need no CloudArch account or API key. Source analysis runs on your computer. Importing a report into CloudArch visualizes that report; it does not independently verify where it came from.

1. Install the CLI

In your repository, with Node.js 20 or later:

npm install -D https://cloud-arch.tech/downloads/cloud-arch-architecture-cli-0.1.0.tgz

This is a versioned package download from CloudArch, not a package published to the npm registry. The commands below use the installed local binary. Commit the dependency and lockfile changes through your normal review process.

2. Design and export a contract

Open CloudArch’s architecture workspace. Add modules and specify:

• a responsibility and source paths relative to the repository root;
• allowed dependencies on other module IDs;
• public entrypoint files, if other modules must use a fixed interface;
• architecture decisions and checks the agent must run separately.

A directory path ends in /; an exact source-file path can define a smaller boundary. An empty public API list permits imports of any file inside that module. List entrypoint files to restrict those imports.

Export the contract and save the downloaded architecture.json as architecture/contract.json in the repository. Exporting or importing a file in the browser does not approve it in Git or configure repository protection.

Alternatively, start from the bundled example:

./node_modules/.bin/cloudarch-architecture init

init refuses to overwrite an existing contract. Edit its example module paths to match real source files before running a check. Review and commit the initial contract as the team’s baseline.

3. Give the agent a task and check its changes

./node_modules/.bin/cloudarch-architecture context \
  --task "Add order cancellation" \
  --output architecture/agent-brief.md
 
./node_modules/.bin/cloudarch-architecture check \
  --output architecture/report.json

The brief includes module responsibilities, permitted dependencies, decisions and required checks. The JSON report contains findings and observed edges, plus the contract digest, source commit and dirty state.

A report can be BLOCK with complete: false when both violations and incomplete analysis exist. Open the architecture workspace, import the matching contract and import architecture/report.json to inspect findings on the graph. A report for a different contract or an older source snapshot cannot establish that current code passes.

4. Connect Codex or Claude Code

Add the following instruction to AGENTS.md. Include equivalent guidance in CLAUDE.md, or import AGENTS.md there with @AGENTS.md:

Before implementation, run:
./node_modules/.bin/cloudarch-architecture context --task "<task>"
Follow the responsibilities and boundaries in architecture/contract.json.
After changes, run the architecture check and the listed required checks.
Fix violations or propose a contract change for separate human acceptance.
Do not silently loosen the contract to make a check pass.

For tool-based access, register the local stdio server. Replace both absolute paths with the installed executable and the repository to inspect. Absolute paths avoid dependence on the agent client’s working directory.

Codex:

codex mcp add cloudarch-architecture -- \
  /absolute/path/to/repository/node_modules/.bin/cloudarch-architecture \
  mcp --root /absolute/path/to/repository

Claude Code:

claude mcp add --transport stdio --scope local cloudarch-architecture -- \
  /absolute/path/to/repository/node_modules/.bin/cloudarch-architecture \
  mcp --root /absolute/path/to/repository

The Claude command uses local project scope; see Claude Code’s MCP configuration guide for other scopes. Quote paths containing spaces. Both clients launch the same server with these tools:

To use a separate trusted baseline, append --accepted-contract /absolute/path/to/trusted-main/architecture/contract.json to the server command. Tool calls cannot change the server’s root or accepted contract path. Use a trusted installation of the CLI when reviewing candidate code.

5. Propose and accept architectural changes

Save proposed rules as architecture/proposal.json, or export a changed draft from the architecture workspace. Compare it without accepting it:

./node_modules/.bin/cloudarch-architecture propose \
  --candidate architecture/proposal.json \
  --output architecture/proposal-review.json

The result includes the proposed contract, changes and canonical digest. A reviewer decides whether the new responsibility or dependency is appropriate. Neither this command nor the browser replaces an accepted repository baseline.

6. Enforce acceptance outside the agent

By default, local checks use the working architecture/contract.json. An agent can edit that file, so a local green result alone cannot enforce accepted architecture. In CI, run a trusted checker from the accepted revision against candidate source and supply the accepted contract explicitly:

/absolute/path/to/trusted-cli/cloudarch-architecture check \
  --root /absolute/path/to/candidate \
  --accepted-contract /absolute/path/to/trusted-main/architecture/contract.json \
  --output /absolute/path/to/report.json

A changed candidate contract then produces CONTRACT_CHANGED; source is still checked against accepted rules. Never install or execute candidate scripts in a privileged checker job. Protect the workflow, checker and contract independently, and require the check and human review before merge.

CloudArch’s own workflow posts architecture/accepted-contract on the exact PR head. An authorized owner can approve a new contract with a separate manual run bound to the PR number, exact head SHA and canonical contract digest. The trusted checker still runs every structural check under those explicitly approved rules. This workflow is repository-specific and is not installed by the npm command.