Skip to content

Commit a50ff91

Browse files
conico974conico974
committed
Add SKILL.md for porting PRs and AGENTS.md for coding guidelines
1 parent cb4e81d commit a50ff91

2 files changed

Lines changed: 244 additions & 0 deletions

File tree

‎.claude/skills/port-pr/SKILL.md‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
---
2+
name: port-pr
3+
description: Port PRs or commits from another repository. Use when you need to bring changes from a source repo. Invoke with /port-pr <commit-or-pr> <source-repo-path>
4+
argument-hint: <commit-or-pr> <source-repo-path>
5+
disable-model-invocation: true
6+
---
7+
8+
# Port PR Skill
9+
10+
This skill enables porting PRs/commits from another repository into this repository.
11+
12+
## Required Inputs
13+
14+
This skill receives arguments via `$ARGUMENTS`:
15+
- `$0` or `$ARGUMENTS[0]`: Commit reference (hash or PR URL)
16+
- `$1` or `$ARGUMENTS[1]`: Source repo path
17+
18+
## Workflow
19+
20+
### 1. Extract Commit Information
21+
22+
**For commit hash:**
23+
```bash
24+
git diff <commit>^..<commit>
25+
git log -1 --format="%s%n%n%b" <commit>
26+
```
27+
28+
**For PR URL:**
29+
```bash
30+
gh pr view <url> --json mergeCommit,title,body
31+
git diff <mergeCommit>^..<mergeCommit>
32+
```
33+
34+
Run these commands in the source repository using `workdir` parameter.
35+
36+
### 2. Analyze Changes
37+
38+
- Identify all files changed, added, and deleted
39+
- Understand the purpose and scope of the change
40+
- Note any dependencies or related changes
41+
42+
### 3. Map to Target Repository
43+
44+
- Find equivalent files in this repository
45+
- Identify any structural differences between repos
46+
- Note files that don't exist or have different paths
47+
48+
### 4. Ask for Guidance
49+
50+
Before implementing, ask the user for clarification when:
51+
- A file doesn't exist in the target repo
52+
- The code structure differs significantly between repos
53+
- The feature/change may not apply to this repository
54+
- There's ambiguity about how to adapt the changes
55+
56+
### 5. Implement Changes
57+
58+
Apply similar changes following this repository's conventions:
59+
- Follow AGENTS.md guidelines (formatting, imports, naming)
60+
- Maintain consistent code style with surrounding code
61+
- Use explicit file extensions (`.js`) for local imports
62+
- Use `node:` prefix for Node.js built-ins
63+
64+
### 6. Verification
65+
66+
After implementation, run:
67+
```bash
68+
pnpm code:checks
69+
```
70+
71+
This runs formatting, linting, and TypeScript checks.
72+
73+
### 7. Summary
74+
75+
Provide a summary of:
76+
- What was ported
77+
- Any adaptations made
78+
- Files modified/created
79+
- Any remaining TODOs or follow-up items

‎AGENTS.md‎

Lines changed: 165 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,165 @@
1+
# AGENTS.md
2+
3+
Guidelines for AI coding agents working in this repository.
4+
5+
## Project Overview
6+
7+
This is a monorepo for OpenNext.js adapters, enabling Next.js deployment to various platforms (AWS Lambda, Cloudflare Workers, Node.js). The repository uses pnpm workspaces with multiple packages under `packages/` and example applications under `examples/` and `examples-cloudflare/`.
8+
9+
## Build/Lint/Test Commands
10+
11+
### Root-level commands (run from repository root)
12+
13+
```bash
14+
# Install dependencies
15+
pnpm install
16+
17+
# Build all packages
18+
pnpm build
19+
20+
# Build only opennext packages
21+
pnpm build:opennext
22+
23+
# Run linter
24+
pnpm lint
25+
26+
# Fix linting issues
27+
pnpm lint:fix
28+
29+
# Check formatting
30+
pnpm fmt
31+
32+
# Fix formatting issues
33+
pnpm fmt:fix
34+
35+
# TypeScript type checking (all packages)
36+
pnpm ts:check
37+
38+
# Run all code checks (fmt + lint + ts:check)
39+
pnpm code:checks
40+
41+
# Run all unit tests
42+
pnpm test
43+
44+
# Run e2e tests
45+
pnpm e2e:test
46+
```
47+
48+
### Running single tests
49+
50+
```bash
51+
# Run a specific test file in the cloudflare package
52+
pnpm --filter @opennextjs/cloudflare vitest run path/to/test.spec.ts
53+
54+
# Run tests matching a pattern in the tests-unit package
55+
pnpm --filter tests-unit vitest run --testNamePattern="test name pattern"
56+
57+
# Run a single test file with vitest directly
58+
cd packages/tests-unit && pnpm vitest run tests/core/routing/matcher.test.ts
59+
60+
# Run tests in watch mode
61+
pnpm --filter tests-unit vitest
62+
63+
# Run tests in a specific package
64+
pnpm --filter @opennextjs/cloudflare test
65+
```
66+
67+
### Package-specific commands
68+
69+
```bash
70+
# Build a specific package
71+
pnpm --filter @opennextjs/cloudflare build
72+
73+
# Type check a specific package
74+
pnpm --filter @opennextjs/cloudflare ts:check
75+
```
76+
77+
## Code Style Guidelines
78+
79+
### Imports
80+
81+
- Use explicit file extensions (`.js`) for local imports: `import { foo } from "./bar.js"`
82+
- Use Node.js built-in imports with `node:` prefix: `import fs from "node:fs"`
83+
- Group imports logically: built-ins first, then external packages, then local modules
84+
- Use workspace protocol for internal packages: `"@opennextjs/aws": "workspace:*"`
85+
86+
### TypeScript
87+
88+
- TypeScript strict mode is enabled via `@tsconfig/strictest`
89+
- Use explicit type annotations for function parameters and return types
90+
- Prefer `type` for object types, `interface` for extensible types
91+
- Use `import type` for type-only imports
92+
- Avoid `any` - use `unknown` or specific types; if unavoidable, add `// oxlint-disable @typescript-eslint/no-explicit-any` comment
93+
- Target ES2022 for compilation
94+
95+
### Formatting
96+
97+
- Tabs for indentation (check .editorconfig if present)
98+
- Single quotes for strings
99+
- Trailing commas in objects/arrays
100+
- Semicolons are required
101+
102+
### Naming Conventions
103+
104+
- camelCase for variables and functions
105+
- PascalCase for types, interfaces, and classes
106+
- SCREAMING_SNAKE_CASE for constants
107+
- kebab-case for file names: `my-component.ts`, `use-cache.ts`
108+
- `.spec.ts` suffix for test files (unit tests use vitest)
109+
- `.test.ts` suffix for test files in tests-unit package
110+
111+
### Error Handling
112+
113+
- Throw descriptive `Error` objects with context
114+
- Use typed errors when specific error handling is needed
115+
- Log errors with console.error/console.log for CLI commands
116+
- Handle async errors with try/catch or .catch()
117+
118+
### File Organization
119+
120+
- Source code in `src/` directory
121+
- Test files co-located with source (`.spec.ts`) or in separate tests directory (`.test.ts`)
122+
- Export public API through `index.ts` files
123+
- Use barrel exports: `export * from "./module.js"`
124+
- Configuration files at package root
125+
126+
### Testing
127+
128+
- Use vitest for unit tests
129+
- Use `describe`/`test`/`expect` from vitest
130+
- Test file naming: `*.spec.ts` for co-located tests, `*.test.ts` for tests-unit package
131+
- Mock external dependencies with `vi.mock()` and `vi.fn()`
132+
- Run tests in Node.js environment (not jsdom) by default
133+
134+
### Comments and Documentation
135+
136+
- Use JSDoc comments for public APIs
137+
- Document complex logic with inline comments
138+
- Use `// TODO(username)` or `// TODO: description` for TODOs
139+
- Keep comments concise and relevant
140+
141+
## Package Manager
142+
143+
This project uses **pnpm** exclusively. Do not use npm or yarn commands.
144+
145+
```bash
146+
# Add a dependency to a specific package
147+
pnpm --filter <package-name> add <dependency>
148+
149+
# Add a dev dependency
150+
pnpm --filter <package-name> add -D <dependency>
151+
152+
# Run a script in a specific package
153+
pnpm --filter <package-name> <script-name>
154+
```
155+
156+
## Pre-commit Checks
157+
158+
Before committing, ensure:
159+
160+
1. `pnpm fmt:fix` - Code is properly formatted
161+
2. `pnpm lint:fix` - No linting errors
162+
3. `pnpm ts:check` - TypeScript compiles without errors
163+
4. `pnpm test` - All tests pass
164+
165+
Run `pnpm code:checks` to verify all checks pass.

0 commit comments

Comments
 (0)