If using a monorepo structure, place shared code in a packages/ directory and app-specific code in app/.
Use Taskfile.yml commands for development, testing, and deployment tasks.
Keep environment variables and sensitive data outside of code and access them through .env files or similar configuration.

Iron Laws

ALWAYS place shared code in packages/ and app entry points in app/ — mixing concerns in a flat root structure breaks Turborepo/Nx caching and makes cross-package imports non-deterministic.
NEVER commit .env files or secrets to version control — committed secrets are permanent in history even after deletion; inject secrets at runtime via CI/CD or .env.local (gitignored).
ALWAYS use Taskfile.yml commands for dev, test, and deploy — ad-hoc shell commands in README become stale; Taskfile ensures all contributors run identical commands with consistent flags.
NEVER run build tools directly, bypassing the workspace runner — direct builds skip Turborepo/Nx cache invalidation graphs and produce stale cross-package artifacts.
ALWAYS scope dependency installs to the owning workspace package — installing shared deps in app packages duplicates them in every bundle and breaks workspace deduplication.

Anti-Patterns

Anti-Pattern	Why It Fails	Correct Approach
Mixing app and shared code in flat root	Breaks dependency graph; caching incorrect; circular imports likely	Place shared modules in `packages/`; app entry points in `app/`; enforce with import rules
Committing `.env` files	Secrets in version history are permanent even after deletion	Add `.env*` to `.gitignore`; use `.env.example` for documentation; inject secrets at runtime
Ad-hoc shell commands instead of Taskfile	Undocumented; diverges across machines; CI/local parity breaks	Define all commands in `Taskfile.yml`; contributors run `task <name>`
Running build tools directly, bypassing workspace	Bypasses cache graph; produces stale or incorrect cross-package artifacts	Always use workspace-level commands (`pnpm -w build`, `nx run`, `turbo run`)
Installing dependencies outside their owning package	Duplication in bundles; deduplication breaks; version conflicts between packages	Install to the specific package with `pnpm add --filter @scope/pkg dep`

Before starting:

cat .claude/context/memory/learnings.md

After completing: Record any new patterns or exceptions discovered.

ASSUME INTERRUPTION: Your context may reset. If it's not in memory, it didn't happen.