harper-best-practices — Claude Code skill: Harper development rules

---
name: harper-best-practices
description: Best practices for building Harper applications, covering schema definition,
  automatic APIs, authentication, custom resources, and data handling.
  Triggers on tasks involving Harper database design, API implementation,
  and deployment.
license: Apache-2.0
metadata:
  author: harper
  version: '1.0.0'
---

# Harper Best Practices

Guidelines for building scalable, secure, and performant applications on Harper. These practices cover everything from initial schema design to advanced deployment strategies.

## When to Use

Reference these guidelines when:

- Defining or modifying database schemas
- Implementing or extending REST/WebSocket APIs
- Handling authentication and session management
- Working with custom resources and extensions
- Optimizing data storage and retrieval (Blobs, Vector Indexing)
- Deploying applications to Harper Fabric

## How It Works

1. Review the requirements for the task (schema design, API needs, or infrastructure setup).
2. Consult the relevant category under "Rule Categories by Priority" to understand the impact of your decisions.
3. Apply specific rules from the "Quick Reference" section below by reading their detailed rule files.
4. If you're building a new table, prioritize the `schema-` rules.
5. If you're extending functionality, consult the `logic-` and `api-` rules.
6. Validate your implementation against the `ops-` rules before deployment.

## Examples

See the concrete examples embedded in each rule subsection below (GraphQL schemas, REST query patterns, and deployment workflow snippets).

<!-- BEGIN GENERATED INDEX -->

## Rule Categories by Priority

| Priority | Category             | Impact | Prefix    |
| -------- | -------------------- | ------ | --------- |
| 1        | Schema & Data Design | HIGH   | `schema-` |
| 2        | API & Communication  | HIGH   | `api-`    |
| 3        | Logic & Extension    | MEDIUM | `logic-`  |
| 4        | Infrastructure & Ops | MEDIUM | `ops-`    |

## Quick Reference

### 1. Schema & Data Design (HIGH)

- `adding-tables-with-schemas` — Guidelines for adding tables to a Harper database using GraphQL schemas.
- `schema-design-tooling` — Best practices for Harper schema design, including core directives and GraphQL tooling configuration.
- `defining-relationships` — How to define and use relationships between tables in Harper using GraphQL.
- `vector-indexing` — How to enable and query vector indexes for similarity search in Harper.
- `using-blob-datatype` — How to use the Blob data type for efficient binary storage in Harper.
- `handling-binary-data` — How to store and serve binary data like images or audio in Harper.

### 2. API & Communication (HIGH)

- `automatic-apis` — How to use Harper's automatically generated REST and WebSocket APIs.
- `querying-rest-apis` — How to use query parameters to filter, sort, and paginate Harper REST APIs.
- `real-time-apps` — How to build real-time features in Harper using WebSockets and Pub/Sub.
- `checking-authentication` — How to handle user authentication and sessions in Harper Resources.

### 3. Logic & Extension (MEDIUM)

- `custom-resources` — How to define custom REST endpoints with JavaScript or TypeScript in Harper.
- `extending-tables` — How to add custom logic to automatically generated table resources in Harper.
- `programmatic-table-requests` — How to interact with Harper tables programmatically using the `tables` object.
- `typescript-type-stripping` — How to run TypeScript files directly in Harper without a build step.
- `caching` — How to implement integrated data caching in Harper from external sources.

### 4. Infrastructure & Ops (MEDIUM)

- `deploying-to-harper-fabric` — How to deploy a Harper application to Harper Fabric with the CLI, check that the release was certified, and roll back by activating a previous release's `deployment_id`.
- `deploying-from-ci` — How to deploy a Harper application from GitHub Actions with OIDC trusted publishing, so CI stores no Harper credential, including the one-command setup with `harper deploy setup=true provider=github-actions`.
- `creating-a-fabric-account-and-cluster` — How to create a Harper Fabric account, organization, and cluster.
- `creating-harper-apps` — How to initialize a new Harper application using the CLI.
- `serving-web-content` — How to serve static files and integrated Vite/React applications in Harper.
- `logging` — Best practices for logging in Harper, including console capture, the granular logger interface, and programmatic log retrieval.
- `load-env` — How to load environment variables from .env files into a Harper application using the loadEnv plugin.
- `v5-upgrade` — Breaking changes and recommended updates when migrating a Harper application to v5.
- `delegating-to-the-built-in-agent` — How to delegate tasks to Harper's built-in agent via the CLI and the agent operations API.

<!-- END GENERATED INDEX -->

## How to Use

Read individual rule files for detailed explanations and code examples:

```
rules/adding-tables-with-schemas.md
rules/schema-design-tooling.md
rules/automatic-apis.md
rules/creating-harper-apps.md
rules/logging.md
```

## Full Compiled Document

For the complete guide with all rules expanded: `AGENTS.md`