Add Claude Code conventions to CLAUDE.md and .claude/rules/ by sdkennedy2 · Pull Request #295 · DataDog/build-plugins

sdkennedy2 · 2026-03-30T15:58:03Z

Motivation

Recurring PR feedback on recent build-plugins contributions revealed patterns that should be codified so they're caught earlier by Claude Code rather than surfacing in reviews. These conventions were distilled from reviewer comments across PRs #289-292.

Changes

Three additions:

1. CLAUDE.md — new Code Conventions section covering:

No any/as escape hatches (with concrete repo-specific alternatives)
Use existing repo utilities (doRequest, @dd/core/helpers/fs, test mock helpers)
No unnecessary optionality
DRY with existing code
Consistent dependency versions across the monorepo

2. .claude/rules/testing.md (auto-applies to **/*.test.ts):

Use existing test helpers and mocks
No timing-based waits
Meaningful tests over implementation-mirroring
Follow cases + test.each pattern

3. .claude/rules/plugin-development.md (auto-applies to packages/plugins/**):

Dependency-inject bundler functionality rather than importing directly
Encapsulate bundler-specific behavior in sub-plugins (e.g. getVitePlugin())
Use factory's global context for bundler references
Follow established plugin patterns

Also un-gitignored .claude/rules/ so these rules are shared with the team (same as .claude/commands/).

QA Instructions

Verify .claude/rules/testing.md and .claude/rules/plugin-development.md are present and tracked
Verify CLAUDE.md Code Conventions section reads correctly
Verify .gitignore allows .claude/rules/ while still ignoring other .claude/ files

Blast Radius

Claude Code configuration only — no runtime code changes. Affects how Claude Code generates code in this repo.

sdkennedy2 · 2026-03-30T15:58:17Z

Add Claude Code conventions to CLAUDE.md and .claude/rules/ #295 👈 (View in Graphite)
master

This stack of pull requests is managed by Graphite. Learn more about stacking.

sdkennedy2 · 2026-03-30T16:02:55Z

.gitignore


 .claude/*
 !.claude/commands/*
+!.claude/rules/


Apparently you need to add to add this line if the rules folder was previously gitignored.

sarenji · 2026-03-30T16:10:10Z

CLAUDE.md

+  - HTTP requests: `doRequest` from `@dd/core/helpers/request` (not raw `fetch`)
+  - File operations: `rm` from `@dd/core/helpers/fs` (not `fs/promises` directly)
+  - Types: `@dd/core/types` for shared types like `GlobalContext`, `Logger`, etc.
+  - Test mocks: `getMockLogger` and other helpers from `packages/tests/src/_jest/helpers/mocks`


These special pointers seem super helpful. Maybe it'd also help to more broadly point to certain directories where these helpers exist. Such as:

@dd/core/helpers

and packages/tests/src/*/helpers

I'll let @yoannmoinet give a better picture of what other helpers exist if any

Or perhaps Claude is smart enough to figure it out.

The trade-off that went through my head was, if we add too much detail then the CLAUDE.md could become out of sync with the code. I wasn't quite sure what the right level of resolution was to include. I'm happy update this though.

Yep, that's one reason to more broadly point to directories rather than specific helpers.

I'd suggest to not use suggestions for a single one, having two + etc. sounds good, but when we only use one like getMockLogger or rm without suggesting that there may be more, would make Claude not consider it for its usage/research.

yoannmoinet

Two small comments.

yoannmoinet · 2026-03-30T20:01:51Z

CLAUDE.md

+- **No TypeScript suppression comments**: Don't use `@ts-ignore`, `@ts-expect-error`, or `@ts-nocheck` to suppress type errors. Fix the underlying type issue instead.
+- **Use existing repo utilities**: Before writing new helpers, check what already exists:
+  - HTTP requests: `doRequest` from `@dd/core/helpers/request` (not raw `fetch`)
+  - File operations: `rm` from `@dd/core/helpers/fs` (not `fs/promises` directly)


I'm worried that if we precise rm only here, it won't take it into consideration for other fs functions.

That makes sense. I'll remove the reference to rm. That should hopefully generalize it to all file operations.

yoannmoinet · 2026-03-30T20:04:21Z

CLAUDE.md

+  - HTTP requests: `doRequest` from `@dd/core/helpers/request` (not raw `fetch`)
+  - File operations: `rm` from `@dd/core/helpers/fs` (not `fs/promises` directly)
+  - Types: `@dd/core/types` for shared types like `GlobalContext`, `Logger`, etc.
+  - Test mocks: `getMockLogger` and other helpers from `packages/tests/src/_jest/helpers/mocks`


I'd suggest to not use suggestions for a single one, having two + etc. sounds good, but when we only use one like getMockLogger or rm without suggesting that there may be more, would make Claude not consider it for its usage/research.

…ies instead of specific functions

yoannmoinet

LGTM

sdkennedy2 · 2026-04-01T18:24:18Z

/merge

gh-worker-devflow-routing-ef8351 · 2026-04-01T18:24:23Z

View all feedbacks in Devflow UI.

2026-04-01 18:24:22 UTC ℹ️ Start processing command /merge

2026-04-01 18:24:28 UTC ℹ️ MergeQueue: waiting for PR to be ready

This pull request is not mergeable according to GitHub. Common reasons include pending required checks, missing approvals, or merge conflicts — but it could also be blocked by other repository rules or settings.
It will be added to the queue as soon as checks pass and/or get approvals. View in MergeQueue UI.
Note: if you pushed new commits since the last approval, you may need additional approval.
You can remove it from the waiting list with /remove command.

2026-04-01 18:54:24 UTC ℹ️ MergeQueue: This merge request was already merged

This pull request was merged directly.

sdkennedy2 changed the title ~~Improve no-any convention with concrete repo-specific patterns~~ Add Claude Code conventions to CLAUDE.md and .claude/rules/ Mar 30, 2026

Add no-ts-suppression convention to CLAUDE.md

47edb4b

sdkennedy2 force-pushed the sdkennedy2/claude-rules branch from e823664 to 47edb4b Compare March 30, 2026 16:00

sdkennedy2 commented Mar 30, 2026

View reviewed changes

sdkennedy2 marked this pull request as ready for review March 30, 2026 16:03

sdkennedy2 requested a review from yoannmoinet as a code owner March 30, 2026 16:03

sarenji approved these changes Mar 30, 2026

View reviewed changes

yoannmoinet reviewed Mar 30, 2026

View reviewed changes

Generalize helper references in CLAUDE.md — point to modules/director…

483a4d5

…ies instead of specific functions

yoannmoinet approved these changes Apr 1, 2026

View reviewed changes

gh-worker-dd-devflow-36fce6 bot added the mergequeue-status: waiting label Apr 1, 2026

yoannmoinet merged commit 9977260 into master Apr 1, 2026
5 checks passed

yoannmoinet deleted the sdkennedy2/claude-rules branch April 1, 2026 18:54

gh-worker-dd-devflow-36fce6 bot added mergequeue-status: done and removed mergequeue-status: waiting labels Apr 1, 2026

Conversation

sdkennedy2 commented Mar 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation

Changes

QA Instructions

Blast Radius

Uh oh!

sdkennedy2 commented Mar 30, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

yoannmoinet left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

yoannmoinet left a comment

Choose a reason for hiding this comment

Uh oh!

sdkennedy2 commented Apr 1, 2026

Uh oh!

gh-worker-devflow-routing-ef8351 bot commented Apr 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

sdkennedy2 commented Mar 30, 2026 •

edited

Loading

gh-worker-devflow-routing-ef8351 bot commented Apr 1, 2026 •

edited

Loading