Skip to content

Commit 59cc6e8

Browse files
rhuanbarretorhuanbarreto
committed
docs: make claude.md more concise
1 parent 74a0d54 commit 59cc6e8

1 file changed

Lines changed: 43 additions & 137 deletions

File tree

‎CLAUDE.md‎

Lines changed: 43 additions & 137 deletions
Original file line numberDiff line numberDiff line change
@@ -1,177 +1,83 @@
11
# CLAUDE.md
22

3-
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4-
5-
## Project Overview
6-
7-
Archgate is a CLI tool for AI governance in software development. It enforces Architecture Decision Records (ADRs) as executable rules — combining human-readable documents with machine-checkable checks.
8-
9-
The CLI dogfoods itself: its own development is governed by Archgate ADRs stored in `.archgate/adrs/`.
10-
11-
AI-powered features (review, capture) are delivered as a **Claude Code plugin** in a separate repository (`archgate/claude-code-plugin`), not via direct Anthropic API calls. The CLI remains standalone for deterministic operations.
3+
Archgate is a CLI tool for AI governance via Architecture Decision Records (ADRs) — combining human-readable docs with machine-checkable rules. The CLI dogfoods itself via ADRs in `.archgate/adrs/`. AI features are delivered as a Claude Code plugin (`archgate/claude-code-plugin`), not via direct API calls.
124

135
## Technology Stack
146

157
- **Runtime:** Bun (>=1.2.21) — not Node.js compatible
16-
- **Language:** TypeScript (strict mode, ESNext target, ES modules)
8+
- **Language:** TypeScript (strict mode, ESNext, ES modules)
179
- **CLI framework:** Commander.js (`@commander-js/extra-typings`)
18-
- **Linter:** Oxlint
19-
- **Formatter:** Prettier
20-
- **Commits:** Conventional Commits enforced by commitlint
10+
- **Linter:** Oxlint | **Formatter:** Prettier | **Commits:** Conventional Commits
2111

2212
## Commands
2313

2414
```bash
25-
# Run the CLI locally
26-
bun run src/cli.ts <command>
27-
28-
# Lint
29-
bun run lint # runs oxlint
30-
31-
# Type check
32-
bun run typecheck # runs tsc --build
33-
34-
# Format check
35-
bun run format:check # runs prettier --check
36-
37-
# Format fix
38-
bun run format # runs prettier --write
39-
40-
# Tests
41-
bun test # runs all tests
42-
bun run test:watch # watch mode
43-
44-
# Full repo validation (MANDATORY before completing any task)
45-
bun run validate # runs lint + typecheck + prettier + test + ADR check
46-
47-
# Build standalone binaries
48-
bun run build # builds all targets (darwin-arm64, linux-x64)
49-
bun run build:darwin # builds macOS arm64 binary only
50-
bun run build:linux # builds Linux x64 binary only
51-
52-
# Commit with conventional commit wizard
53-
bun run commit
15+
bun run src/cli.ts <command> # run CLI locally
16+
bun run lint # oxlint
17+
bun run typecheck # tsc --build
18+
bun run format # prettier --write
19+
bun run format:check # prettier --check
20+
bun test # all tests
21+
bun run validate # MANDATORY: lint + typecheck + format + test + ADR check
22+
bun run build # binaries → dist/ (darwin-arm64, linux-x64)
23+
bun run commit # conventional commit wizard
5424
```
5525

56-
Binaries are output to `dist/`. Each binary has a companion `.sha256` checksum file.
57-
5826
## Validation Gate
5927

60-
**`bun run validate` must pass before any task is considered complete.** This is a hard requirement for all agents and developers. The script runs the full validation pipeline in order:
61-
62-
1. **Lint** (`oxlint .`) — Static analysis
63-
2. **Typecheck** (`tsc --build`) — Type safety
64-
3. **Format** (`prettier --check .`) — Code formatting
65-
4. **Test** (`bun test`) — All unit and integration tests
66-
5. **ADR check** (`archgate check`) — Architecture Decision Record compliance
67-
68-
The pipeline is fail-fast: if any step fails, subsequent steps do not run. Fix all failures before proceeding. This mirrors the CI pipeline in `.github/workflows/code-pull-request.yml`.
28+
**`bun run validate` must pass before any task is considered complete.** Fail-fast pipeline: lint → typecheck → format → test → ADR check. Mirrors CI in `.github/workflows/code-pull-request.yml`.
6929

7030
## Architecture
7131

72-
### Entry Point & Command Registration
73-
74-
`src/cli.ts` is the entry point (shebang `#!/usr/bin/env bun`). It performs bootstrap checks (Bun version, OS compatibility, Git availability), then explicitly imports and registers commands via `register*Command(program)` functions. It also starts a background update check that prints a notice after the command completes.
32+
### Commands
7533

76-
### Current Commands
34+
Entry point: `src/cli.ts` (shebang `#!/usr/bin/env bun`). Commands registered via `register*Command(program)`.
7735

78-
| Command | File | Description |
79-
| --------------- | ------------------------ | ---------------------------------------------------- |
80-
| `init` | `commands/init.ts` | Initialize `.archgate/` governance skeleton |
81-
| `check` | `commands/check.ts` | Run automated ADR compliance checks |
82-
| `adr create` | `commands/adr/create.ts` | Create a new ADR interactively |
83-
| `adr list` | `commands/adr/list.ts` | List all ADRs (supports `--json`, `--domain` filter) |
84-
| `adr show <id>` | `commands/adr/show.ts` | Display a specific ADR by ID |
85-
| `adr update` | `commands/adr/update.ts` | Update an existing ADR by ID |
86-
| `mcp` | `commands/mcp.ts` | Start MCP server for AI tool integration |
87-
| `upgrade` | `commands/upgrade.ts` | Upgrade the CLI binary via GitHub Releases |
88-
| `clean` | `commands/clean.ts` | Remove `~/.archgate/` cache directory |
89-
90-
### Claude Code Plugin (separate repo)
91-
92-
The Claude Code plugin lives in `archgate/claude-code-plugin` (https://github.com/archgate/claude-code-plugin). It provides AI-powered governance features: a developer agent (`archgate:developer`), role-based skills (architect, quality-manager, adr-author, onboard), and MCP connection to `archgate mcp`. The plugin's `.mcp.json` calls `archgate mcp` — the binary must be installed and in PATH first.
93-
94-
Run `archgate:onboard` once to initialize governance for a new project.
95-
96-
### Formats (`src/formats/`)
97-
98-
| Module | Purpose |
99-
| ---------- | -------------------------------------------------------------------------------- |
100-
| `adr.ts` | ADR frontmatter Zod schema, types (derived via `z.infer<>`), parsing, validation |
101-
| `rules.ts` | `RuleSetSchema`, `RuleConfig`, `RuleContext`, `defineRules()` |
102-
103-
**Validation convention:** Zod schemas are the single source of truth for data shapes. TypeScript types are derived from schemas via `z.infer<>` — never define separate interfaces. Use `safeParse()` for validation and to get typed data without unsafe casts. Reuse schema shapes (e.g., `AdrFrontmatterSchema.shape.domain`) across commands and MCP tools to avoid duplicating enums.
104-
105-
### Helpers (`src/helpers/`)
106-
107-
| Module | Purpose |
108-
| ------------------------ | ----------------------------------------------------------------------------------- |
109-
| `paths.ts` | Manages `~/.archgate/` (internal cache) and `.archgate/` (project governance) paths |
110-
| `log.ts` | `logDebug`, `logInfo`, `logError`, `logWarn` using `styleText` from `node:util` |
111-
| `adr-templates.ts` | Generate example ADR and blank ADR templates |
112-
| `adr-writer.ts` | Write and update ADR markdown files on disk |
113-
| `init-project.ts` | Initialize `.archgate/` project structure and Claude plugin settings |
114-
| `claude-settings.ts` | Manage `.claude/settings.local.json` for Archgate plugin integration |
115-
| `git.ts` | Check for Git; auto-install via Homebrew (macOS) or apt (Linux) |
116-
| `getParentFolderName.ts` | Extract project name from git root or folder basename |
117-
| `update-check.ts` | Background version check against GitHub Releases (24h cache, non-fatal) |
36+
| Command | File | Description |
37+
| --------------- | ------------------------ | -------------------------------------- |
38+
| `init` | `commands/init.ts` | Initialize `.archgate/` skeleton |
39+
| `check` | `commands/check.ts` | Run ADR compliance checks |
40+
| `adr create` | `commands/adr/create.ts` | Create ADR interactively |
41+
| `adr list` | `commands/adr/list.ts` | List ADRs (`--json`, `--domain`) |
42+
| `adr show <id>` | `commands/adr/show.ts` | Show ADR by ID |
43+
| `adr update` | `commands/adr/update.ts` | Update ADR by ID |
44+
| `mcp` | `commands/mcp.ts` | Start MCP server |
45+
| `upgrade` | `commands/upgrade.ts` | Upgrade CLI binary via GitHub Releases |
46+
| `clean` | `commands/clean.ts` | Remove `~/.archgate/` cache |
11847

11948
### Key Paths
12049

121-
- `~/.archgate/` — CLI cache and downloaded templates
122-
- `~/.archgate/bin/` — Default binary install location (used by install script)
123-
- `.archgate/` — Project governance directory (per-project)
124-
- `.archgate/adrs/` — Architecture Decision Records
125-
- `.archgate/lint/` — Linter-specific rules (e.g., oxlint plugins)
50+
- `~/.archgate/` — CLI cache; `~/.archgate/bin/` — binary install location
51+
- `.archgate/adrs/` — ADRs; `.archgate/lint/` — linter rules
52+
- `src/formats/` — Zod schemas + types (`adr.ts`, `rules.ts`)
53+
- `src/helpers/` — utilities (paths, log, git, templates, adr-writer, etc.)
54+
- `tests/` — mirrors `src/`; fixtures in `tests/fixtures/`
12655

127-
### Tests (`tests/`)
56+
### Formats & Validation
12857

129-
Tests use Bun's built-in test runner. Structure mirrors `src/`:
130-
131-
- `tests/formats/` — Unit tests for parsers and types
132-
- `tests/commands/` — Integration tests for commands
133-
- `tests/fixtures/` — Sample ADR files
58+
Zod schemas are the single source of truth. Types derived via `z.infer<>` — never define separate interfaces. Use `safeParse()`. Reuse `AdrFrontmatterSchema.shape.*` to avoid duplicating enums.
13459

13560
## Conventions
13661

137-
- **Command files** export `register*Command(program)` functions, imported in `src/cli.ts`
138-
- **Commands handle I/O only** — parse args, call engine/helpers, format output; no business logic in commands
139-
- **OS support:** macOS and Linux only (Windows blocked, WSL2 recommended)
140-
- **Dependencies:** Minimal production deps. Prefer Bun built-ins. See `.archgate/adrs/ARCH-006-dependency-policy.md`.
141-
- **Output:** Use `styleText()` from `node:util` for colored output. Support `--json` for machine-readable output. No emoji in CLI output.
142-
- **Exit codes:** 0 = success, 1 = violation/failure, 2 = internal error
143-
- **Testing:** Bun test runner, fixtures in `tests/fixtures/`, temp dirs for filesystem tests
144-
145-
## CI/CD
146-
147-
Three GitHub Actions workflows:
148-
149-
- **`code-pull-request.yml`** — On PR: validates PR title with commitlint, runs `bun run validate` (lint + typecheck + format + test + ADR check). Skips drafts.
150-
- **`release.yml`** — On push to main: creates release PR or publishes release via `@simple-release/npm`. Runs `bun run validate` before publish.
151-
- **`release-binaries.yml`** — On GitHub Release published: builds darwin-arm64 and linux-x64 binaries, uploads to the release, and updates the Homebrew tap formula.
152-
153-
Release is automated via conventional commits (semantic versioning from commit messages).
154-
155-
## Toolchain
156-
157-
Managed via Proto (`.prototools`):
62+
- Commands export `register*Command(program)`, handle I/O only — no business logic
63+
- OS: macOS and Linux only (Windows blocked, WSL2 recommended)
64+
- Output: `styleText()` from `node:util`; `--json` for machine-readable; no emoji
65+
- Exit codes: 0 = success, 1 = violation, 2 = internal error
66+
- Deps: minimal; prefer Bun built-ins (see ARCH-006)
15867

159-
- Bun 1.3.8
160-
- Moon 1.39.4
161-
- Node LTS
162-
- npm 11.6.0
68+
## Toolchain (`.prototools`)
16369

164-
## Self-Governance ADRs
70+
Bun 1.3.8, Moon 1.39.4, Node LTS, npm 11.6.0. Minimum user-facing Bun: `>=1.2.21` (enforced in `src/cli.ts`).
16571

166-
The CLI's own ADRs are in `.archgate/adrs/`:
72+
## Self-Governance ADRs (`.archgate/adrs/`)
16773

16874
- `ARCH-001` — Command structure (register pattern, no business logic)
16975
- `ARCH-002` — Error handling (exit codes, logError)
17076
- `ARCH-003` — Output formatting (styleText, --json, no emoji)
171-
- `ARCH-004` — No barrel files (direct imports, no re-export-only index.ts)
77+
- `ARCH-004` — No barrel files (direct imports only)
17278
- `ARCH-005` — Testing standards (Bun test, fixtures, 80% coverage)
17379
- `ARCH-006` — Dependency policy (minimal deps, Bun built-ins)
17480

17581
## ADR Format
17682

177-
ADRs are markdown files with YAML frontmatter (`id`, `title`, `domain`, `rules`, optional `files` globs). Body sections: Context, Decision, Do's and Don'ts, Consequences (Positive/Negative/Risks), Compliance and Enforcement, References. Companion `.rules.ts` files export check functions via `defineRules()`.
83+
YAML frontmatter (`id`, `title`, `domain`, `rules`, optional `files`). Sections: Context, Decision, Do's and Don'ts, Consequences, Compliance, References. Companion `.rules.ts` exports `defineRules()`.

0 commit comments

Comments
 (0)