|
| 1 | +# TinyEngine — Repository Instructions for Coding Agents |
| 2 | + |
| 3 | +## Purpose and Scope |
| 4 | + |
| 5 | +This file is the canonical source of truth for repo-wide agent instructions. |
| 6 | + |
| 7 | +- Applies to the whole repository unless a closer `AGENTS.md` overrides it for a subtree. |
| 8 | +- `CLAUDE.md` is a compatibility entrypoint that imports this file. Do not maintain a second independent copy of the same rules. |
| 9 | +- Keep this file limited to repo-wide guidance. Package-specific implementation details belong in package-level instruction files. |
| 10 | + |
| 11 | +## Repository Snapshot |
| 12 | + |
| 13 | +- Monorepo: pnpm workspaces + lerna (independent versioning) |
| 14 | +- Primary stack: Vue 3, Vite, JavaScript/TypeScript |
| 15 | +- Package manager: `pnpm` only for interactive work in this repo |
| 16 | +- Designer app: `designer-demo/` |
| 17 | +- Local mock backend: `mockServer/` |
| 18 | + |
| 19 | +## Working Model |
| 20 | + |
| 21 | +- Inspect the affected package, its `package.json`, and the nearest instruction file before editing. |
| 22 | +- Keep changes scoped. Do not normalize unrelated files or rename fixtures just for consistency. |
| 23 | +- Prefer targeted package-level validation over whole-repo commands when possible. |
| 24 | +- Treat `pnpm lint` and `pnpm format` as mutating commands, not read-only verification. |
| 25 | +- Do not invoke `npm` or `yarn` directly for normal repo work. Existing package scripts may still shell out internally; leave that alone unless the task is specifically about package scripts. |
| 26 | + |
| 27 | +## Common Commands |
| 28 | + |
| 29 | +### Read-mostly commands |
| 30 | + |
| 31 | +```sh |
| 32 | +pnpm install |
| 33 | +pnpm dev |
| 34 | +pnpm build:plugin |
| 35 | +pnpm build:alpha |
| 36 | +pnpm --filter @opentiny/tiny-engine-dsl-vue test:unit |
| 37 | +``` |
| 38 | + |
| 39 | +### Mutating commands |
| 40 | + |
| 41 | +```sh |
| 42 | +pnpm lint # ESLint with --fix |
| 43 | +pnpm format # Prettier --write |
| 44 | +``` |
| 45 | + |
| 46 | +Canonical script definitions live in: |
| 47 | + |
| 48 | +- `package.json` |
| 49 | +- `packages/*/package.json` |
| 50 | +- `.github/workflows/push-check.yml` |
| 51 | +- `.github/workflows/Release.yml` |
| 52 | + |
| 53 | +## Verification Matrix |
| 54 | + |
| 55 | +Run the smallest sufficient verification for the change surface, then expand if the change is broad or risky. |
| 56 | + |
| 57 | +1. Docs-only changes: |
| 58 | + No code verification required unless the docs change commands or workflow descriptions that should be checked against source files. |
| 59 | +2. `packages/vue-generator/**`: |
| 60 | + Run the affected testcase or `pnpm --filter @opentiny/tiny-engine-dsl-vue test:unit`. |
| 61 | + If generator behavior changes, run the full `test:unit` suite before handoff and inspect any changed `expected/*.vue` files. |
| 62 | +3. Published library packages under `packages/**`: |
| 63 | + Run the package-local `test` script if one exists. |
| 64 | + Run `pnpm build:plugin` when build output or published package behavior may be affected. |
| 65 | +4. `designer-demo/**` or shared packages consumed by the demo: |
| 66 | + Run `pnpm build:alpha`. |
| 67 | +5. Cross-package build or release-facing changes: |
| 68 | + Run `pnpm build:plugin` and `pnpm build:alpha`. |
| 69 | +6. Config, workspace, CI, or release script changes: |
| 70 | + Verify the directly affected command(s) after approval. |
| 71 | + |
| 72 | +## Approval Boundaries |
| 73 | + |
| 74 | +### Always OK |
| 75 | + |
| 76 | +- Read any source file |
| 77 | +- Run targeted tests and builds |
| 78 | +- Edit implementation files inside existing packages |
| 79 | +- Add or update tests that match the scope of the change |
| 80 | +- Update docs that reflect current repo behavior |
| 81 | + |
| 82 | +### Ask First |
| 83 | + |
| 84 | +- Changing workspace, lerna, pnpm, ESLint, Prettier, or TypeScript configuration |
| 85 | +- Modifying CI workflows, release scripts, or publish flows |
| 86 | +- Upgrading major dependencies or changing pinned overrides |
| 87 | +- Reordering or adding/removing default vue-generator attribute hooks |
| 88 | +- Large-scale edits to generated mappings or vendored patches |
| 89 | + |
| 90 | +When asking first, include: |
| 91 | + |
| 92 | +- what you want to change |
| 93 | +- why the current rules or implementation are insufficient |
| 94 | +- what verification you would run after approval |
| 95 | + |
| 96 | +### Never |
| 97 | + |
| 98 | +- Use `npm` or `yarn` directly for routine repo commands |
| 99 | +- Skip hooks with `--no-verify` |
| 100 | +- Hardcode versions for workspace packages |
| 101 | +- Edit `patches/` without understanding the upstream issue and the patch purpose |
| 102 | +- Rewrite generated expectations or snapshots without validating the new output first |
| 103 | + |
| 104 | +## Task-Specific Expectations |
| 105 | + |
| 106 | +- Bug fix: |
| 107 | + Add or update a regression test when behavior changes. |
| 108 | +- Refactor: |
| 109 | + Preserve behavior and prove it with targeted verification. |
| 110 | +- Snapshot or generated output change: |
| 111 | + Explain why the output changed and list the affected fixture directories. |
| 112 | +- Commit or PR work: |
| 113 | + Only do it if asked. Use Conventional Commits and target `develop` unless the user specifies otherwise. |
| 114 | + |
| 115 | +## Gotchas |
| 116 | + |
| 117 | +- `pnpm install` is enforced by `preinstall`; npm and yarn are rejected for direct repo usage. |
| 118 | +- `pnpm lint` writes fixes. Use it deliberately. |
| 119 | +- CI relies on `build:plugin` and `build:alpha`, not only lint or unit tests. |
| 120 | +- Test directories such as `test/`, `expected/`, and `output/` are not always linted; do not treat lint success as fixture validation. |
0 commit comments