Skip to content

docs: add AGENTS.md for universal AI agent support #30

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
gcko merged 1 commit into from
Jan 1, 2026
Merged

docs: add AGENTS.md for universal AI agent support #30

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
184 changes: 184 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,184 @@
# AGENTS.md

Instructions for AI coding agents working with this repository.

## Project Overview

Recce UI (`@datarecce/ui`) is a React component library wrapper that packages the open-source Recce project for npm distribution.

**Key Architecture:** Git submodule pattern
- `src/` - Wrapper layer (re-exports, minimal overrides)
- `recce-source/` - Git submodule pointing to DataRecce/recce OSS repo
- `dist/` - Built output (generated, never edit)

**Tech Stack:** React 18/19, MUI 7, TypeScript 5.9, pnpm, tsdown

---

## Critical Constraints

### Do NOT:
- Edit files in `recce-source/` directly (OSS code; use patches if needed)
- Use npm or yarn (must use pnpm; locked via .npmrc)
- Skip submodule initialization (clone with `--recursive`)
- Bypass pre-commit hooks (never use `--no-verify`)
- Edit generated files in `dist/` (regenerate via `pnpm build`)
- Add dependencies not in recce-source (keep synced with OSS)
- Use interactive git commands (`git rebase -i`, `git add -i`)
- Commit node_modules/ or dist/

### Always:
- Initialize submodules: `git submodule init && git submodule update`
- Use pnpm for all package operations
- Run `pnpm type:check` before committing
- Run `make sync` when updating from OSS
- Build before local testing: `make build && make link`
- Keep VERSION file and package.json version in sync

---

## Essential Commands

### Setup
```bash
git clone --recursive https://github.com/DataRecce/recce-ui.git
cd recce-ui
pnpm install
make build
```

### Daily Development
```bash
pnpm dev # Watch mode (rebuilds on changes)
pnpm build # Full build (tsdown + CSS aggregation)
pnpm type:check # Type check (filters OSS errors)
pnpm type:check:all # Type check including OSS errors
pnpm test # Run tests with Vitest
pnpm check:exports # Find new/stale component exports
```

### Submodule Management
```bash
make sync # Update submodule, sync deps, install
make verify # Full verification (sync + build + type-check + check-exports)
```

### Before Committing
```bash
pnpm type:check # Must pass
pnpm build # Ensure build succeeds
```

### Local Testing (in consumer project)
```bash
# In recce-ui:
make link

# In consumer project:
pnpm link --global @datarecce/ui
```

---

## Repository Layout

```
recce-ui/
├── src/ # Wrapper layer (edit here)
│ ├── index.ts # Main entry (re-exports)
│ ├── components/ # Component re-exports
│ ├── api/ # API utilities
│ ├── hooks/ # Custom hooks
│ ├── types/ # Type definitions
│ ├── lib/ # Custom overrides
│ └── global-styles.css # Theme CSS variables
├── recce-source/ # Git submodule (DO NOT EDIT)
│ └── js/src/ # Actual component source
├── scripts/ # Build scripts
├── dist/ # Generated output (DO NOT EDIT)
└── Makefile # Command shortcuts
```

## Where to Add Code

| Change Type | Location | Notes |
|-------------|----------|-------|
| New component export | `src/components/index.ts` | Re-export from recce-source |
| New hook export | `src/hooks/index.ts` | Re-export from recce-source |
| New type export | `src/types/index.ts` | Re-export from recce-source |
| Custom override | `src/lib/` | When OSS needs wrapper-specific logic |
| Build script | `scripts/` | Build-time processing |
| Global styles | `src/global-styles.css` | Theme config, CSS variables |

---

## Commit Conventions

### Sign-off Required (DCO)
Every commit must include a sign-off line:
```bash
git commit -s -m "feat(components): add LineageView export"
```

### Conventional Commit Format
```
<type>(<scope>): <description>

Signed-off-by: Name <email>
```

**Types:** `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`

**Examples:**
```bash
git commit -s -m "feat(components): add LineageView export"
git commit -s -m "fix(build): ensure global-styles loaded first"
git commit -s -m "chore(deps): sync dependencies from recce-source"
```

### Branch Naming
All branches from `main` with prefix:
- `feature/` - New features
- `fix/` - Bug fixes
- `hotfix/` - Critical production fixes

### PR Requirements
- All type checks must pass
- Build must succeed
- Main branch requires PRs (no direct commits)

---

## Common Pitfalls

### Submodule Not Initialized
```
Error: Cannot find module '../recce-source/js/src/components'
```
**Fix:** `git submodule init && git submodule update`

### Type Errors in OSS Code
```
pnpm type:check:all shows errors in recce-source/
```
**Expected:** Use `pnpm type:check` (filters OSS errors we don't control)

### Missing Component Export
```
Module has no exported member 'ComponentName'
```
**Fix:** Add re-export to `src/components/index.ts`, then `pnpm build`

### Dependency Mismatch
```
WARN Issues with peer dependencies found
```
**Fix:** `pnpm run sync:deps && pnpm install`

---

## Additional Resources

- **[CLAUDE.md](./CLAUDE.md)** - Extended documentation for Claude Code (architecture deep-dives, patterns, troubleshooting)
- **[CONTRIBUTING.md](./CONTRIBUTING.md)** - Human contributor guide
- **[ARCHITECTURE.md](./ARCHITECTURE.md)** - System design documentation
173 changes: 21 additions & 152 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,99 +1,31 @@
# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
Extended guidance for Claude Code (claude.ai/code) when working with this repository.

## Overview

Recce UI (`@datarecce/ui`) is a React component library for building data validation and review interfaces. It provides the UI components used in [Recce](https://github.com/DataRecce/recce), a data validation tool for dbt projects. The library enables developers to create data comparison, profiling, and validation workflows with pre-built, production-ready components.

**Key Architecture:** This is a wrapper library that packages the open-source Recce project for npm distribution. It uses a git submodule pattern where actual component source lives in `recce-source/` (pointing to the main Recce repository), while `src/` contains only re-exports and minimal customizations for the npm package.

## Critical Constraints & Guidelines

### Do NOT:

- ❌ **Skip submodule initialization**: Always clone with `--recursive` flag or run `git submodule init && git submodule update`
- ❌ **Edit files in recce-source/ directly**: This is OSS code from the main Recce repo; use patches if modifications are needed
- ❌ **Use npm or yarn**: Must use `pnpm` as specified in .npmrc and package.json
- ❌ **Bypass pre-commit hooks**: Never use `--no-verify` on commits; hooks enforce quality standards
- ❌ **Commit node_modules or dist/**: These are build artifacts and dependencies (gitignored)
- ❌ **Edit generated files in dist/**: Always regenerate via `pnpm build` or `make build`
- ❌ **Publish without running build**: `prepublishOnly` hook ensures this, but never bypass it
- ❌ **Add dependencies not in recce-source**: Keep dependency lists synchronized with OSS package
- ❌ **Use interactive git commands**: Never use `git rebase -i`, `git add -i` (interactive prompts don't work)

### Always:

- ✅ **Initialize submodules with --recursive flag**: `git clone --recursive` or use submodule commands after clone
- ✅ **Use pnpm for package management**: Package manager is locked to pnpm via .npmrc
- ✅ **Run make sync when updating from OSS**: This updates submodule, syncs deps, and installs
- ✅ **Build before testing locally with link**: Run `make build` then `make link` for local testing
- ✅ **Run type:check before committing**: Ensure `pnpm type:check` passes to catch errors early
- ✅ **Keep dependencies in sync with recce-source**: Use `pnpm run sync:deps` to synchronize
- ✅ **Update VERSION file with package.json**: Both must match for consistency
- ✅ **Test component exports**: Run `pnpm check:exports` to find new/stale exports
> **For universal agent instructions, see [AGENTS.md](./AGENTS.md).**

## Git Development Practices
## What's in Each File

### Branch Naming
| AGENTS.md (All AI Agents) | CLAUDE.md (Claude-Specific) |
|---------------------------|----------------------------|
| Critical constraints | Architecture deep-dives |
| Essential commands | Build system internals |
| Repository layout | Code patterns & examples |
| Commit conventions | Path alias configuration |
| Common pitfalls | CSS bundling strategy |
| | Type generation details |
| | Extended troubleshooting |
| | Key principles |

All new code MUST be developed in a branch with one of these prefixes, branched directly from `main`:

- `feature/` - New features or enhancements
- `fix/` - Bug fixes
- `hotfix/` - Critical production fixes

```bash
# Create a new feature branch
git checkout main
git pull origin main
git checkout -b feature/my-new-feature
```

### Commit Requirements

**1. Sign-off (DCO):** Every commit MUST include a "Signed-off-by:" line per the [Developer Certificate of Origin](https://developercertificate.org/):

```bash
git commit -s -m "Your commit message"
```

**2. Semantic/Conventional Commits:** Use structured commit messages:

```
<type>(<scope>): <description>

[optional body]

[optional footer]
Signed-off-by: Your Name <your.email@example.com>
```

**Types:**

- `feat` - New feature
- `fix` - Bug fix
- `docs` - Documentation only
- `style` - Formatting, no code change
- `refactor` - Code change that neither fixes a bug nor adds a feature
- `test` - Adding or updating tests
- `chore` - Maintenance tasks (deps, build, CI)
---

**Examples:**
This file provides extended guidance for Claude Code beyond the basics in AGENTS.md.

```bash
git commit -s -m "feat(components): add LineageView export"
git commit -s -m "fix(build): ensure global-styles loaded first"
git commit -s -m "docs: update CLAUDE.md with submodule workflow"
git commit -s -m "chore(deps): sync dependencies from recce-source"
```
## Overview

**Additional Guidelines:**
Recce UI (`@datarecce/ui`) is a React component library for building data validation and review interfaces. It provides the UI components used in [Recce](https://github.com/DataRecce/recce), a data validation tool for dbt projects. The library enables developers to create data comparison, profiling, and validation workflows with pre-built, production-ready components.

- Commit frequently during development
- Use worktrees for parallel work (`git worktree --help`)
- Main branch requires PRs
- Pre-commit hooks enforce quality—never skip them
**Key Architecture:** This is a wrapper library that packages the open-source Recce project for npm distribution. It uses a git submodule pattern where actual component source lives in `recce-source/` (pointing to the main Recce repository), while `src/` contains only re-exports and minimal customizations for the npm package.

## Code Organization Philosophy

Expand Down Expand Up @@ -261,72 +193,7 @@ recce-ui/

## Development Commands

### Initial Setup

**Prerequisites:**
- Node.js >= 20 (check with `node --version`)
- pnpm (install with `npm install -g pnpm`)
- Git with submodule support

**First Time Setup:**

```bash
# Clone repository WITH submodules
git clone --recursive https://github.com/DataRecce/recce-ui.git
cd recce-ui

# If you forgot --recursive, initialize submodules now:
git submodule init
git submodule update

# Install dependencies
pnpm install

# Build the library
make build

# Run type checking
make type-check
```

### Build and Development

```bash
# Show all available commands
make help

# Build the package (tsdown + CSS aggregation)
make build
# OR
pnpm build

# Watch mode for development (rebuilds on file changes)
pnpm dev

# Type checking (filters out OSS errors)
make type-check
# OR
pnpm type:check

# Type checking including OSS errors (for debugging)
make type-check-all
# OR
pnpm type:check:all

# Check for new/stale component exports
make check-exports
# OR
pnpm check:exports

# Clean build artifacts
make clean

# Full rebuild (clean + build)
make rebuild

# Run all checks (sync + build + type-check + check-exports)
make verify
```
> **Basic commands are in [AGENTS.md](./AGENTS.md#essential-commands).** This section covers extended workflows.

### Submodule Management

Expand Down Expand Up @@ -702,6 +569,8 @@ alias: {

## Common Errors & Fixes

> **Quick fixes for common issues are in [AGENTS.md](./AGENTS.md#common-pitfalls).** This section provides extended troubleshooting.

### Submodule Not Initialized

**Error:**
Expand Down
Loading