Skip to main content
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:
LayerWhatWhen LoadedPurpose
CLAUDE.md (root)~55 linesEvery sessionNon-obvious architecture rules
packages/*/CLAUDE.md~30-55 lines eachWhen working in that packagePackage-specific patterns
.agents/features/*.md~60 lines eachWhen Claude explores the featureEntity schemas, services, data flows
.claude/rules/3-5 lines eachEvery sessionCritical safety checks (entity registration, data isolation, edition safety)
.agents/skills/30-65 lines eachWhen invokedStep-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

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: 
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

SituationCommandWhy
Starting unrelated feature/clearWipe old context, start clean
Continuing same feature next dayOpen Claude in same directoryAuto-loads CLAUDE.md
Claude keeps making same mistake/clear + rewrite promptCorrection loops waste context
Long session (45+ min)/compactPrevent quality degradation
Context feels bloated/compactSummarize 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)

DayMorningAfternoon
MonPlan Feature A (explore + plan)Implement Feature A
TueFinish A, test, PRPlan + start Feature B
WedFinish BPlan + implement Feature C
ThuFinish C, test, PRFeature D (full cycle in 1 day)
FriFeature 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

claude                        # Opens Claude Code in current directory

​
Onboarding (First Week)

1

Day 1

Read this guide. Install Claude Code. Read root CLAUDE.md (~55 lines).
2

Day 2-3

Pick a small feature (5-10 files). Follow the full workflow: brief, Plan Mode, implement, test, PR. Expect 4-6 hours.
3

Day 4

Pick a medium feature (15-25 files). Practice /clear when stuck. Use the /add-feature skill.
4

Day 5

Try 2 parallel sessions on different features. Practice tab-switching.
5

After Week 1

You should be shipping 1 feature/day comfortably.