From 3d2698aa7a7d2d9d4e7d83db74cbf57e6c546653 Mon Sep 17 00:00:00 2001 From: jinhojang6 Date: Sat, 9 May 2026 16:29:16 +0900 Subject: [PATCH] feat: add operating guide for AI coding agents and update README structure --- AGENTS.md | 110 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 70 ++++++++++++++++++++-------------- 2 files changed, 152 insertions(+), 28 deletions(-) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000000..684f961fb1 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,110 @@ +# AGENTS.md + +Operating guide for AI coding agents working in this repo. Keep changes minimal, match the conventions below, and prefer reading the linked docs over inferring intent. + +## Repo shape + +pnpm + Turborepo monorepo. Node `>=20.9`, pnpm `10.9`. + +| Path | Role | +| --- | --- | +| `apps/web` | Public Next.js 16 site. Tailwind v4, `next-intl`, static export. Port `3000`. | +| `apps/cms` | Payload CMS 3.x admin app (Next.js 16 + Postgres). Port `3001`, admin at `/admin`. | +| `packages/content` | Content schemas, loaders for `content/**`, GitHub mutation helpers, locale registry. | +| `packages/ui` | Shared React primitives + SVG icon components. | +| `packages/tokens` | Design tokens. | +| `packages/types` | Shared types incl. Payload-generated (`generate-types`). | +| `packages/config` | Shared ESLint / TypeScript / Prettier config. | +| `content/**` | **Production source of truth** for page copy and structured data (pages, press, circles, builders-hub, site). | +| `docs/**` | Deployment, plan, page/component specs. Read before designing. | + +Apps are entrypoints only. New shared logic goes in a package, not duplicated across apps. + +## Commands + +Run from repo root unless noted. + +```bash +pnpm install +pnpm dev # turbo: web on :3000, cms on :3001 +pnpm build # web static export + cms next build +pnpm test # vitest in apps/web +pnpm lint # eslint --max-warnings 0 across workspaces +pnpm check-types # next typegen + tsc --noEmit +pnpm generate-types # cms only — regenerates packages/types/src/payload.ts +``` + +`apps/web/start` is `python3 -m http.server` over the static `out/` build, not `next start`. Treat the web app as static. + +## Architecture rules + +1. **`apps/web` does not call the GitHub API at request time.** It reads `content/**` at build. Preview deploys build per PR; production deploys from `master`. +2. **CMS edits are PRs, not DB writes.** Payload's Postgres only stores users, sessions, drafts, and PR cache. All published content changes go through `develop` via GitHub PR (see `apps/cms/src/services/content-workflow/`). +3. **Branch model:** `develop` is the default + staging branch. `master` is production (created when production deploys spin up). Direct commits to either are blocked by branch protection. CMS-generated PRs target `develop`. +4. **Env access is typed.** Use `apps/web/lib/env.ts`; never reach into `process.env` from feature code. Add new vars to `env.ts`. +5. **The CMS refuses to boot in production-like envs without `NEXT_PUBLIC_SERVER_URL` / `NEXT_PUBLIC_WEB_URL`** — silent localhost fallback breaks CORS/cookies. Don't "fix" this by removing the assertion. + +## i18n + +- Active locales come from `apps/web/i18n/routing.ts` (today: `['en']`). `Language` type is pre-declared as `'en' | 'fr' | 'ko'` so adding a locale is a routing change, not a schema change. +- UI chrome → `apps/web/messages/.json` (`next-intl`). +- Page copy / structured data → `content/**//...` JSON files. +- **All user-facing strings go through i18n keys.** Includes titles, descriptions, labels, and `createDefaultMetadata` args. Use `getTranslations` in server components, `useTranslations` in client components. Hardcoded strings will be rejected. +- A locale added to `routing.ts` makes its `.json` files required at build time — there is no silent fallback. +- After `next build`, `apps/web/scripts/strip-default-locale-prefix.sh` strips the `/en` prefix from the static export. Don't bypass it. + +## Code conventions + +- **Repo files are English only.** Committed code, comments, docs, copy. Chat replies can be in any language; files cannot. +- **Icons are React SVG components** exported from `@repo/ui` (`packages/ui/src/icons`). If a designed icon is missing, stop and ask for a Figma export — don't substitute Unicode/text. +- **The λ brand mark is ``** from `@repo/ui`. Size via `size`, color via parent `text-*` (the SVG uses `currentColor`). Never `` or `λ`. +- **Every clickable element gets `cursor-pointer`** in its Tailwind className: buttons, `onClick` handlers, anchors, clickable cards. +- **Visuals match Figma 1:1.** Pull the spec (font sizes, fills, gaps, padding) from Figma before implementing. See `docs/components.md` for canonical node IDs and `docs/web-pages.md` for per-page references. +- **Types on public APIs.** Exported functions, shared utilities, component props. Use `interface` for object shapes, `type` for unions/intersections. Avoid `any`; use `unknown` + narrowing for external input. +- **Immutability.** Spread/copy, never mutate. `Readonly` on inputs where it clarifies intent. +- **No `console.log` in committed code.** +- **Follow existing file organization.** Many small focused files over large ones. Routes live under `apps/web/app/[locale]//`; section components under `apps/web/components/sections/
/`. + +## Content + CMS + +Schemas: `packages/content/src/schemas/` (Zod). Loaders: `packages/content/src/loaders/` (typed, fail loudly on missing required locale files). + +When changing a schema: +1. Update the Zod schema in `packages/content/src/schemas/`. +2. Update / add the corresponding loader. +3. Update fixtures under `content/**`. +4. If the CMS edits this collection, update the matching Payload collection in `apps/cms/src/collections/` and the workflow service in `apps/cms/src/services/content-workflow/`. +5. Run `pnpm generate-types` (CMS) and `pnpm check-types`. + +Payload collections: `Pages`, `Circles`, `Ideas`, `Rfps`, `ContentChangeRequests`, `Users`. The first four mutate via the GitHub PR workflow (see `save-as-pr.ts`, `save-idea-as-pr.ts`, `save-rfp-as-pr.ts`). + +## Testing + +- Vitest lives in `apps/web` (`pnpm test` from root or app). Add tests beside the code in `__tests__/` folders. +- Playwright is the standard for E2E if/when added. +- For UI/frontend changes, **start the dev server and verify in a browser** before reporting done. Type-check passing ≠ feature working. + +## Git + PRs + +- **Never auto-commit or push without explicit instruction.** +- **Never add co-author / `Co-Authored-By` lines** to commits in this repo. +- Conventional commit prefixes: `feat`, `fix`, `refactor`, `docs`, `test`, `chore`, `perf`, `ci`. +- PR base branch is `develop`. + +## Where to look first + +- `docs/deployment.md` — env vars, Vercel dev/staging vs self-hosted prod, Postgres setup, troubleshooting. +- `docs/cms-github-content-plan.md` — canonical schema + workflow design. +- `docs/web-pages.md` — per-page Figma references and requirements. +- `docs/components.md` — shared component specs (Nav, Footer, etc.) with Figma node IDs. +- `docs/code-quality-followups.md` — known gaps awaiting design/infra decisions. +- `docs/seo.md` — SEO/metadata expectations. + +## Don't + +- Don't introduce new top-level packages or apps without checking with the user. +- Don't add backwards-compat shims, `_unused` renames, or "removed in vX" comments. Delete cleanly. +- Don't add error-handling for cases that can't occur, or fallbacks that hide misconfiguration. +- Don't write comments that restate the code. Comments explain *why*, only when non-obvious. +- Don't create new `.md` files unless explicitly asked. +- Don't run destructive git operations (`reset --hard`, force push, branch delete) without confirmation. diff --git a/README.md b/README.md index 59b5b475fc..83c5be87a8 100644 --- a/README.md +++ b/README.md @@ -1,42 +1,56 @@ -# logos-turborepo-next-tailwind-i18n-template +# logos-co -A pnpm + Turborepo starter with: +pnpm + Turborepo monorepo for the Logos website and its content CMS. -- `apps/web`: Next.js frontend with Tailwind CSS v4 and `next-intl` -- `apps/cms`: standalone Payload CMS app with Admin dashboard -- `packages/content`: shared content schemas + loaders for `content/**` (consumed by both apps) -- `packages/ui`: shared React UI primitives -- `packages/config`: shared ESLint / TypeScript / Prettier config -- `packages/types`: shared application types, including Payload-generated types +- `apps/web` — public Next.js 16 site (Tailwind v4, `next-intl`, static export) +- `apps/cms` — Payload CMS 3.x admin (Postgres-backed; edits ship as GitHub PRs) +- `packages/content` — content schemas, loaders for `content/**`, GitHub mutation helpers +- `packages/ui` — shared React primitives and SVG icons (``, etc.) +- `packages/tokens` — design tokens +- `packages/types` — shared types incl. Payload-generated +- `packages/config` — shared ESLint / TypeScript / Prettier config +- `content/**` — production source of truth (pages, press, circles, builders-hub, site) -## Why this shape +Apps are entrypoints only. Shared logic lives in packages. The web app reads `content/**` at build time and never calls GitHub at request time. -- Apps stay as entrypoints only. -- Shared code lives in purpose-specific packages. -- The CMS is isolated from the frontend deployment boundary. -- Payload-generated types can be shared without coupling the frontend to Payload runtime packages. +## Requirements -## Commands +Node `>=20.9`, pnpm `10.9.0`. + +## Quick start ```bash pnpm install -pnpm dev -pnpm build -pnpm test -pnpm lint -pnpm check-types -pnpm generate-types +pnpm dev # web → http://localhost:3000, cms → http://localhost:3001 ``` -## Local URLs +Payload Admin: . -- Web: `http://localhost:3000` -- CMS: `http://localhost:3001` -- Payload Admin: `http://localhost:3001/admin` +`apps/cms` requires `PAYLOAD_SECRET` and `DATABASE_URL` (Postgres). Copy `apps/cms/.env.example` to `apps/cms/.env` and fill it in. See [docs/deployment.md](./docs/deployment.md) for the full env matrix. + +## Common scripts + +```bash +pnpm build # web static export + cms build +pnpm test # vitest (apps/web) +pnpm lint # eslint --max-warnings 0 +pnpm check-types # next typegen + tsc --noEmit +pnpm generate-types # regenerate packages/types/src/payload.ts from Payload schema +``` + +## Branch model + +- `develop` — default branch + staging. CMS-generated content PRs target this. +- `master` — production (created when production deploys spin up). + +Direct pushes to either are blocked by branch protection. ## Documentation -- [docs/cms-github-content-plan.md](./docs/cms-github-content-plan.md) — Schema, loader, and CMS-via-GitHub workflow plan (canonical) -- [docs/deployment.md](./docs/deployment.md) — Self-hosted production deployment + Vercel dev/staging, required env vars, Turso DB setup, security headers, troubleshooting -- [docs/web-pages.md](./docs/web-pages.md) — Per-page web requirements -- [docs/components.md](./docs/components.md) — Component-level Figma references +- [AGENTS.md](./AGENTS.md) — conventions and rules for AI agents working in this repo +- [docs/deployment.md](./docs/deployment.md) — env vars, Vercel dev/staging, self-hosted production +- [docs/cms-github-content-plan.md](./docs/cms-github-content-plan.md) — schema + GitHub workflow design +- [docs/web-pages.md](./docs/web-pages.md) — per-page web requirements (Figma references) +- [docs/components.md](./docs/components.md) — shared component specs +- [docs/seo.md](./docs/seo.md) — SEO and metadata expectations +- [docs/code-quality-followups.md](./docs/code-quality-followups.md) — known gaps awaiting decisions