> ## Documentation Index
> Fetch the complete documentation index at: https://www.activepieces.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# AI Engineering Guide
How to use our Claude Code setup to ship features from a single prompt (hopefully 😄).
This guide is for engineers, not AI. Claude should not read this file.
## What We Built
Our repo has a layered AI assistance system:
| Layer | What | When Loaded | Purpose |
| ----------------------- | ------------------ | -------------------------------- | ---------------------------------------------------------------------------- |
| `CLAUDE.md` (root) | \~55 lines | Every session | Non-obvious architecture rules |
| `packages/*/CLAUDE.md` | \~30-55 lines each | When working in that package | Package-specific patterns |
| `.agents/features/*.md` | \~60 lines each | When Claude explores the feature | Entity schemas, services, data flows |
| `.claude/rules/` | 3-5 lines each | Every session | Critical safety checks (entity registration, data isolation, edition safety) |
| `.agents/skills/` | 30-65 lines each | When invoked | Step-by-step workflows (`/add-feature`, `/add-entity`, `/add-endpoint`) |
Total context per session: \~150 lines. Claude has \~150 instruction slots — we use them all, nothing wasted.
## The Workflow: Prompt to Feature to Ship
### 1. Write a Clear Brief (5 min)
**Bad:** "add analytics"
**Good:** "Add a project-level analytics dashboard showing flow run count, success rate, and average duration for the last 7/30/90 days. Project-scoped, CE feature, visible to users with READ\_RUN permission."
Include:
* What it does (1-2 sentences)
* Who sees it (role/permission)
* CE, EE, or both
* Any constraints (must work embedded, must respect quotas, etc.)
### 2. Explore (Plan Mode) — 15 min
Press `Shift+Tab` twice to enter Plan Mode, then paste your brief.
Claude will:
* Read relevant feature files in `.agents/features/` for the modules you'll touch
* Explore existing patterns in the codebase
* Ask you clarifying questions
* Propose which files to create/modify
You review and refine. This is where 80% of the value comes from — getting the plan right before writing code.
### 3. Implement — 30-90 min
Exit Plan Mode. Claude executes the plan.
For full-stack features, tell Claude: "Use `/add-feature`" — this triggers our custom skill with the full cross-cutting checklist (shared types, entity + migration, service, controller, frontend, tests, verify).
For just a database entity: `/add-entity "my_feature"`
For just an API endpoint: `/add-endpoint "description"`
Claude will:
* Create files following our patterns (references real code, not examples)
* Register entities in `getEntities()` (rules enforce this)
* Add migrations to `getMigrations()`
* Set up `securityAccess` on every endpoint
* Filter queries by `projectId`/`platformId`
* Create frontend feature folder with API client + hooks
### 4. Test — 10-30 min
Tell Claude: "Write API tests for this feature and run them."
Claude will:
* Create test file at `test/integration/ce/{feature}.test.ts`
* Use `setupTestEnvironment()` + `createTestContext(app)`
* Run `npm run test-api`
* Fix failures and re-run
### 5. Verify and Ship — 10 min
```bash theme={null}
npm run lint-dev # Claude runs this automatically
npm run test-api # Verify all tests pass
```
Then: "Create a PR for this" — Claude handles branch, commit, and PR creation.
## Parallel Features (2-3 at Once)
Open multiple terminal tabs, each with its own Claude session:
```bash theme={null}
Tab 1: claude --worktree # Feature A (backend-heavy)
Tab 2: claude --worktree # Feature B (frontend-heavy)
Tab 3: claude --worktree # Feature C (piece/integration)
```
Each tab gets its own git worktree (isolated branch, no conflicts). While Tab 1 is running tests, switch to Tab 2 and keep building.
Practical limit: 3 parallel sessions. Beyond that, context-switching overhead exceeds gains.
## Session Management
| Situation | Command | Why |
| -------------------------------- | ----------------------------- | ------------------------------ |
| Starting unrelated feature | `/clear` | Wipe old context, start clean |
| Continuing same feature next day | Open Claude in same directory | Auto-loads `CLAUDE.md` |
| Claude keeps making same mistake | `/clear` + rewrite prompt | Correction loops waste context |
| Long session (45+ min) | `/compact` | Prevent quality degradation |
| Context feels bloated | `/compact` | Summarize and continue fresh |
If you've corrected Claude twice on the same thing, `/clear` and rewrite the prompt with what you learned. Don't accumulate corrections.
## Code Review Checklist (for AI-Generated Code)
* [ ] Logic matches the plan you approved
* [ ] Queries filter by `projectId` or `platformId`
* [ ] New entity registered in `getEntities()`
* [ ] Migration added to `getMigrations()`
* [ ] Every endpoint has `securityAccess` config
* [ ] EE code stays in `src/app/ee/` (no cross-imports)
* [ ] Tests exist and pass
* [ ] No `as SomeType` casting
* [ ] No `any` types
* [ ] Zod error messages use i18n keys
* [ ] `@activepieces/shared` version bumped (if changed)
## Weekly Rhythm (5 Features/Week Target)
| Day | Morning | Afternoon |
| --- | ------------------------------- | --------------------------------- |
| Mon | Plan Feature A (explore + plan) | Implement Feature A |
| Tue | Finish A, test, PR | Plan + start Feature B |
| Wed | Finish B | Plan + implement Feature C |
| Thu | Finish C, test, PR | Feature D (full cycle in 1 day) |
| Fri | Feature E (or polish D) | Code review, merge, retrospective |
Planning on Day N, implementing on Day N+1 produces better code than doing both in the same session. The overnight break lets you think about edge cases.
## Tips from Top Performers
1. **Front-load the brief.** A clear 3-sentence description saves 30 min of Claude wandering. Include: what, who, CE/EE, constraints.
2. **Let Plan Mode run.** Don't skip it. The 15 minutes of exploration prevents 2 hours of wrong-direction coding.
3. **Use the skills.** `/add-feature` exists for a reason — it encodes every step we've learned from past mistakes.
4. **Read the feature docs yourself.** Before starting a feature in a module, spend 2 minutes reading its `.agents/features/*.md`. You'll ask better questions.
5. **Don't babysit.** Start Claude on a task, switch to another tab, come back when it's done. Check notifications.
6. **Small PRs > big PRs.** Ship each feature as its own PR. Don't bundle.
7. **Test commands in the brief.** Include "success looks like: this test passes, this API returns 200, this page renders" in your prompt.
8. **Trust the rules.** Our `.claude/rules/` enforce entity registration, edition safety, and data isolation. Claude follows these every time.
## Quick Reference
```bash Start working theme={null}
claude # Opens Claude Code in current directory
```
```bash Plan before implementing theme={null}
# Press Shift+Tab twice for Plan Mode
```
```bash Custom skills theme={null}
/add-feature "description" # Full-stack feature workflow
/add-entity "name" # Database entity + migration
/add-endpoint "description" # API endpoint + controller
```
```bash Session management theme={null}
/clear # Hard reset (new feature)
/compact # Soft reset (continue, less context)
```
```bash Verification theme={null}
npm run lint-dev # Lint + auto-fix
npm run test-api # Run API tests
npm run test-unit # Run unit tests
```
```bash Ship theme={null}
CLAUDE_PUSH=yes git push -u origin HEAD
```
## Onboarding (First Week)
Read this guide. Install Claude Code. Read root `CLAUDE.md` (\~55 lines).
Pick a small feature (5-10 files). Follow the full workflow: brief, Plan Mode, implement, test, PR. Expect 4-6 hours.
Pick a medium feature (15-25 files). Practice `/clear` when stuck. Use the `/add-feature` skill.
Try 2 parallel sessions on different features. Practice tab-switching.
You should be shipping 1 feature/day comfortably.