Skip to content

Commit ba3c218

Browse files
GregHolmesGregHolmes
authored
chore(repo): add claude regen skill docs (#35)
* chore(repo): add Claude regen skill docs * chore(repo): add Claude regeneration docs for Java SDK
1 parent 2f9a2c5 commit ba3c218

3 files changed

Lines changed: 116 additions & 0 deletions

File tree

‎.claude/skills/prepare-regen.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Prepare Repo for Fern SDK Regeneration
2+
3+
Triggers: prepare regen, prepare for regeneration, prep for fern, new sdk gen, prepare sdk gen
4+
5+
## Steps
6+
7+
Read AGENTS.md for full context on the regeneration workflow and freeze classification rules.
8+
9+
1. Fetch latest `main` and create a new branch: `<YOUR_INITIALS>/sdk-gen-<YYYY-MM-DD>` (use today's date).
10+
2. Push the branch to origin.
11+
3. Create an empty commit (`chore: initialize SDK regeneration branch`) if needed, then create a PR titled `chore: SDK regeneration <YYYY-MM-DD>`.
12+
4. Read `.fernignore` and classify each entry using the rules in AGENTS.md:
13+
- **Permanently frozen**: entirely hand-written, no Fern equivalent. NEVER touch these.
14+
- **Temporarily frozen**: Fern-generated with manual patches. These get swapped.
15+
5. For each **temporarily frozen** file only:
16+
- Copy the file to `<filename>.bak` alongside the original.
17+
- In `.fernignore`, replace the original path with the `.bak` path (protects our patch, lets Fern overwrite the original).
18+
6. Stage the updated `.fernignore` and all `.bak` files.
19+
7. Commit as `chore: unfreeze files pending regen` and push.
20+
8. Report the PR URL and confirm the branch is ready for generator output.

‎.claude/skills/review-regen.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# Review Fern SDK Regeneration
2+
3+
Triggers: review regen, review regeneration, diff regen, compare regen, post regen review
4+
5+
## Steps
6+
7+
Read AGENTS.md for full context on the regeneration workflow and freeze classification rules.
8+
9+
1. Find all `.bak` files in the repo — these are our pre-regen manually-patched versions (protected by `.fernignore`).
10+
2. For each `.bak` file, diff it against the corresponding newly generated file to show what changed.
11+
3. Identify which manual patches are still needed (the `.bak` has changes the generator doesn't produce).
12+
4. Present a summary of findings to the user, grouped by category:
13+
- Patches no longer needed (generator now handles it)
14+
- Patches still needed (must be re-applied)
15+
- New changes from the generator worth noting
16+
5. Wait for user direction on which patches to re-apply.
17+
6. Re-apply confirmed patches to the generated files.
18+
7. In `.fernignore`, replace each `.bak` path back to the original path for files that still need patches.
19+
8. Remove `.fernignore` entries entirely for files where patches are no longer needed.
20+
9. Delete all `.bak` files.
21+
10. Run `make build && make test && make lint` to verify.
22+
11. Commit as `chore: re-apply manual patches after regen` and push.

‎AGENTS.md‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
# Agents
2+
3+
## Fern SDK Regeneration
4+
5+
### Overview
6+
7+
This SDK is generated by [Fern](https://buildwithfern.com/). Most files under `src/main/java/com/deepgram/` are auto-generated and should not be edited directly. Some files are hand-written or carry manual patches and are listed in `.fernignore` to prevent the generator from overwriting them.
8+
9+
When a new Fern generator release is available, we prepare the repo so the generator can overwrite previously frozen files, then re-apply manual patches after reviewing the diff.
10+
11+
### Freeze classification rules
12+
13+
Every entry in `.fernignore` falls into one of two categories. The comment above each entry in `.fernignore` indicates which category it belongs to, but when in doubt, apply these rules:
14+
15+
#### Never unfreeze (permanently frozen)
16+
17+
These files are entirely hand-written or are maintained independently from Fern. The generator would delete or replace them with something unrelated. They must stay in `.fernignore` at all times.
18+
19+
How to identify:
20+
21+
- The file was created by us, not by Fern, such as custom client wrappers or transport abstractions
22+
- The file is a doc, config, build, or CI artifact we maintain independently
23+
- The file lives outside the generated Java package tree or is a manually maintained test/example
24+
25+
Current permanently frozen files:
26+
27+
- `src/main/java/com/deepgram/DeepgramClient.java`, `src/main/java/com/deepgram/AsyncDeepgramClient.java`, `src/main/java/com/deepgram/DeepgramClientBuilder.java`, `src/main/java/com/deepgram/AsyncDeepgramClientBuilder.java` - custom wrapper entrypoints that add Bearer auth, session ID support, and custom transport behavior on top of Fern's generated API client
28+
- `src/main/java/com/deepgram/core/transport/` - hand-written transport abstraction
29+
- `build.gradle`, `settings.gradle`, `gradle/`, `gradlew`, `gradlew.bat`, `pom.xml`, `Makefile` - build and project configuration
30+
- `README.md`, `CHANGELOG.md`, `CONTRIBUTING.md`, `LICENSE` - docs
31+
- `src/test/` - manually maintained tests
32+
- `examples/` - manually maintained examples
33+
- `.editorconfig`, `.githooks/`, `.github/`, `.gitignore` - repo and CI configuration
34+
- `target/` - build output
35+
- `CLAUDE.md`, `AGENTS.md`, `.claude/` - agent files
36+
37+
Note: `.fernignore` also includes flat-path variants such as `src/main/java/DeepgramClient.java` as defensive entries for alternate local generation layouts. Those files do not currently exist in this repo checkout and should not be treated as current maintained source files.
38+
39+
#### Unfreeze for regen (temporarily frozen)
40+
41+
These files are Fern-generated but carry manual patches to fix issues in the generator output. We freeze them to protect our patches between regenerations, but unfreeze them before a regen so we can compare the new output against our patches.
42+
43+
How to identify:
44+
45+
- The file exists in Fern's output - if you removed it from `.fernignore` and ran the generator, Fern would produce a version of it
46+
- Our version is a modified copy of what Fern generates
47+
48+
Current temporarily frozen files:
49+
50+
- `src/main/java/com/deepgram/core/ClientOptions.java` - preserves release-please version markers and correct SDK header constants that Fern currently overwrites
51+
52+
### Prepare repo for regeneration
53+
54+
1. Create a new branch off `main` named `lo/sdk-gen-<YYYY-MM-DD>`.
55+
2. Push the branch and create a PR titled `chore: SDK regeneration <YYYY-MM-DD>` (empty commit if needed).
56+
3. Read `.fernignore` and classify each entry using the rules above.
57+
4. For each temporarily frozen file only:
58+
- Copy the file to `<filename>.bak` alongside the original.
59+
- In `.fernignore`, replace the original path with the `.bak` path. This protects our patched version from the generator while allowing Fern to overwrite the original.
60+
5. Never touch permanently frozen entries. Leave them in `.fernignore` as-is.
61+
6. Commit as `chore: unfreeze files pending regen` and push.
62+
7. The branch is now ready for the Fern generator to push changes.
63+
64+
### After regeneration
65+
66+
The `.bak` files are our manually patched versions protected by `.fernignore`. The original paths now contain the freshly generated versions. By comparing the two, we can see what the generator now produces versus what we had patched.
67+
68+
1. Diff each `.bak` file against the new generated version to understand what changed and whether our patches are still needed.
69+
2. Re-apply any patches that are still necessary to the newly generated files.
70+
3. In `.fernignore`, replace each `.bak` path back to the original path for files that still need patches.
71+
4. Remove `.fernignore` entries entirely for any files where the generator now produces correct output.
72+
5. Delete all `.bak` files once review is complete.
73+
6. Run checks (`./gradlew test`) to verify.
74+
7. Commit as `chore: re-apply manual patches after regen` and push.

0 commit comments

Comments
 (0)
⚡