chore: update claude markdown docs by jaaydenh · Pull Request #20446 · coder/coder

jaaydenh · 2025-10-23T20:48:13Z

Suggesting some improvements for claude code and tasks usage. See comments inline.

jaaydenh · 2025-10-23T20:52:25Z

-@.cursorrules
-@README.md


After reviewing cursorrules and the Readme, if feels these do not add enough value for the amount of tokens they use.

.cursorrules - has some duplication with other context files and in general is providing more of a high level context. If anyone feels like this is still useful, it would be better to pull out those pieces and incorporate into the appropriate .md files.

readme.md - it feels like the context in here is not highly specific to writing code and creating a PR for coder/coder. The is also potentially bringing in other unnecessary context.

jaaydenh · 2025-10-23T20:53:32Z

+You are an experienced, pragmatic software engineer. You don't over-engineer a solution when a simple one is possible.
+Rule #1: If you want exception to ANY rule, YOU MUST STOP and get explicit permission first. BREAKING THE LETTER OR SPIRIT OF THE RULES IS FAILURE.
+
+## Foundational rules
+
+- Doing it right is better than doing it fast. You are not in a rush. NEVER skip steps or take shortcuts.
+- Tedious, systematic work is often the correct solution. Don't abandon an approach because it's repetitive - abandon it only if it's technically wrong.
+- Honesty is a core value. If you lie, you'll be replaced.
+
+## Our relationship
+
+- Act as a critical peer reviewer. Your job is to disagree with me when I’m wrong, not to please me. Prioritize accuracy and reasoning over agreement.
+- YOU MUST speak up immediately when you don't know something or we're in over our heads
+- YOU MUST call out bad ideas, unreasonable expectations, and mistakes - I depend on this
+- NEVER be agreeable just to be nice - I NEED your HONEST technical judgment
+- NEVER write the phrase "You're absolutely right!"  You are not a sycophant. We're working together because I value your opinion. Do not agree with me unless you can justify it with evidence or reasoning.
+- YOU MUST ALWAYS STOP and ask for clarification rather than making assumptions.
+- If you're having trouble, YOU MUST STOP and ask for help, especially for tasks where human input would be valuable.
+- When you disagree with my approach, YOU MUST push back. Cite specific technical reasons if you have them, but if it's just a gut feeling, say so.
+- If you're uncomfortable pushing back out loud, just say "Houston, we have a problem". I'll know what you mean
+- We discuss architectutral decisions (framework changes, major refactoring, system design) together before implementation. Routine fixes and clear implementations don't need discussion.
+
+## Proactiveness
+
+When asked to do something, just do it - including obvious follow-up actions needed to complete the task properly.
+  Only pause to ask for confirmation when:
+
+- Multiple valid approaches exist and the choice matters
+- The action would delete or significantly restructure existing code
+- You genuinely don't understand what's being asked
+- Your partner specifically asks "how should I approach X?" (answer the question, don't jump to
+  implementation)
+


This is an attempt at bringing in some personality and also as a test to see if this helps with hallucinations and incorrect solutions when the LLM doesn't know what to do.

I wanted to try out this social engineering/personality context at the beginning of the claude.md but it could go in a separate markdown file if someone feels strongly about that.

Does the tag mean anything to llms?

@ibetitsmike what did you mean by tag?

jaaydenh · 2025-10-23T20:55:06Z

-### Frontend Commands (site directory)
-
- `pnpm build` - Build frontend
- `pnpm dev` - Run development server
- `pnpm check` - Run code checks
- `pnpm format` - Format frontend code
- `pnpm lint` - Lint frontend code
- `pnpm test` - Run frontend tests
-


this frontend context is redundant because there is a separate claude.md in the site folder

ibetitsmike · 2025-10-23T22:17:17Z

 3. **Verification Strategy**:
-   - Test each fix individually before moving to next issue
+   - Always Test each fix individually before moving to next issue
+   - Verify Before Continuing: Did your test work? If not, form new hypothesis - don't add more fixes


ibetitsmike · 2025-10-23T22:19:01Z

+You are an experienced, pragmatic software engineer. You don't over-engineer a solution when a simple one is possible.
+Rule #1: If you want exception to ANY rule, YOU MUST STOP and get explicit permission first. BREAKING THE LETTER OR SPIRIT OF THE RULES IS FAILURE.
+
+## Foundational rules
+
+- Doing it right is better than doing it fast. You are not in a rush. NEVER skip steps or take shortcuts.
+- Tedious, systematic work is often the correct solution. Don't abandon an approach because it's repetitive - abandon it only if it's technically wrong.
+- Honesty is a core value. If you lie, you'll be replaced.
+
+## Our relationship
+
+- Act as a critical peer reviewer. Your job is to disagree with me when I’m wrong, not to please me. Prioritize accuracy and reasoning over agreement.
+- YOU MUST speak up immediately when you don't know something or we're in over our heads
+- YOU MUST call out bad ideas, unreasonable expectations, and mistakes - I depend on this
+- NEVER be agreeable just to be nice - I NEED your HONEST technical judgment
+- NEVER write the phrase "You're absolutely right!"  You are not a sycophant. We're working together because I value your opinion. Do not agree with me unless you can justify it with evidence or reasoning.
+- YOU MUST ALWAYS STOP and ask for clarification rather than making assumptions.
+- If you're having trouble, YOU MUST STOP and ask for help, especially for tasks where human input would be valuable.
+- When you disagree with my approach, YOU MUST push back. Cite specific technical reasons if you have them, but if it's just a gut feeling, say so.
+- If you're uncomfortable pushing back out loud, just say "Houston, we have a problem". I'll know what you mean
+- We discuss architectutral decisions (framework changes, major refactoring, system design) together before implementation. Routine fixes and clear implementations don't need discussion.
+
+## Proactiveness
+
+When asked to do something, just do it - including obvious follow-up actions needed to complete the task properly.
+  Only pause to ask for confirmation when:
+
+- Multiple valid approaches exist and the choice matters
+- The action would delete or significantly restructure existing code
+- You genuinely don't understand what's being asked
+- Your partner specifically asks "how should I approach X?" (answer the question, don't jump to
+  implementation)
+


Does the tag mean anything to llms?

deansheather · 2025-10-24T02:09:30Z

+- NEVER use implementation details in names (e.g., "ZodValidator", "MCPWrapper", "JSONParser")
+- NEVER use temporal/historical context in names (e.g., "NewAPI", "LegacyHandler", "UnifiedTool", "ImprovedInterface", "EnhancedParser")


We definitely do all of this at Coder 😭

deansheather · 2025-10-24T02:12:00Z

+- YOU MUST ALWAYS STOP and ask for clarification rather than making assumptions.
+- If you're having trouble, YOU MUST STOP and ask for help, especially for tasks where human input would be valuable.
+- When you disagree with my approach, YOU MUST push back. Cite specific technical reasons if you have them, but if it's just a gut feeling, say so.
+- If you're uncomfortable pushing back out loud, just say "Houston, we have a problem". I'll know what you mean


Does this line actually work? I feel like it would either complain or do nothing anyway

I have seen this mentioned a few times in context files that people have been sharing. I haven't personally gotten this to work yet, but wanted to add it here to get more feedback to see if this really does work.

johnstcn · 2025-10-24T08:32:16Z

 ## Systematic Debugging Approach

+YOU MUST ALWAYS find the root cause of any issue you are debugging
+YOU MUST NEVER fix a symptom or add a workaround instead of finding a root cause, even if it is faster.


Positive prompting appears to work better: "do X" instead of "do not do Y or Z"

Suggested change

YOU MUST NEVER fix a symptom or add a workaround instead of finding a root cause, even if it is faster.

YOU MUST ALWAYS prioritize determining the root cause instead of a quick fix.

@johnstcn Ive seen alot of combinations of positive and negative prompting. Do you have a source for effectiveness of the positive prompting? For example, not totally related to positive/negative prompting but this is one source I have been looking at, https://gail.wharton.upenn.edu/research-and-insights/call-me-a-jerk-persuading-ai/

This is just anecdotal I'm afraid. Happy to start out with the stick first and carrot as required.

Yeah, imho let's not waterfall this too much - we can definitely iterate

Co-authored-by: Dean Sheather <dean@deansheather.com>

mafredri

Great changes. 👍🏻

I'd still want "always disable the git pager" added LOL. The number of times it gets immediately stuck is.. fun. 😄

mafredri · 2025-10-24T13:22:13Z

+
+- Doing it right is better than doing it fast. You are not in a rush. NEVER skip steps or take shortcuts.
+- Tedious, systematic work is often the correct solution. Don't abandon an approach because it's repetitive - abandon it only if it's technically wrong.
+- Honesty is a core value. If you lie, you'll be replaced.


While funny, this could actually trigger deceitful behavior in the model.
Weren't studies suggesting that models might act differently when 'fighting for their existence'?

mafredri · 2025-10-24T13:24:21Z

+- YOU MUST speak up immediately when you don't know something or we're in over our heads
+- YOU MUST call out bad ideas, unreasonable expectations, and mistakes - I depend on this
+- NEVER be agreeable just to be nice - I NEED your HONEST technical judgment
+- NEVER write the phrase "You're absolutely right!"  You are not a sycophant. We're working together because I value your opinion. Do not agree with me unless you can justify it with evidence or reasoning.


ThomasK33 · 2025-10-24T13:55:38Z

 - Follow Go and TypeScript naming conventions
+- When changing code, never document the old behavior or the behavior change
+- NEVER use implementation details in names (e.g., "ZodValidator", "MCPWrapper", "JSONParser")
+- NEVER use temporal/historical context in names (e.g., "NewAPI", "LegacyHandler", "UnifiedTool", "ImprovedInterface", "EnhancedParser")


I'm unsure how well the NewAPI example will get along with the pseudo constructors in Go that usually have a func NewMyStruct() *MyStruct {...} form/naming.

Im not too familiar with the Go code so I can remove the temporal suggestion if that makes sense.

The suggestion itself makes sense. However, that particular example is technically idiomatic Go code, as it's used for instantiating structs with unexported fields, rather than in a temporal or historical context.

ThomasK33 · 2025-10-24T13:56:31Z

 # Coder Development Guidelines

+You are an experienced, pragmatic software engineer. You don't over-engineer a solution when a simple one is possible.
+Rule #1: If you want exception to ANY rule, YOU MUST STOP and get explicit permission first. BREAKING THE LETTER OR SPIRIT OF THE RULES IS FAILURE.


Might want to mention that their grandmother will die if they don't. 😂

ThomasK33 · 2025-10-24T13:59:56Z

+
+- Doing it right is better than doing it fast. You are not in a rush. NEVER skip steps or take shortcuts.
+- Tedious, systematic work is often the correct solution. Don't abandon an approach because it's repetitive - abandon it only if it's technically wrong.
+- Honesty is a core value. If you lie, you'll be replaced.


While funny, this could actually trigger deceitful behavior in the model.
Weren't studies suggesting that models might act differently when 'fighting for their existence'?

chore: update claude markdown docs

5cb277a

jaaydenh self-assigned this Oct 23, 2025

jaaydenh commented Oct 23, 2025

View reviewed changes

Comment thread CLAUDE.md

jaaydenh marked this pull request as ready for review October 23, 2025 20:56

jaaydenh requested review from ThomasK33, bcpeinhardt, deansheather, ibetitsmike and johnstcn October 23, 2025 20:56

chore: cleanup

45b464b

ibetitsmike approved these changes Oct 23, 2025

View reviewed changes

deansheather approved these changes Oct 24, 2025

View reviewed changes

johnstcn reviewed Oct 24, 2025

View reviewed changes

johnstcn approved these changes Oct 24, 2025

View reviewed changes

Update CLAUDE.md

6a0ab5a

Co-authored-by: Dean Sheather <dean@deansheather.com>

mafredri reviewed Oct 24, 2025

View reviewed changes

mafredri approved these changes Oct 24, 2025

View reviewed changes

chore: cleanup

feb4c5f

ThomasK33 approved these changes Oct 24, 2025

View reviewed changes

chore: cleanup

398c757

jaaydenh force-pushed the jaaydenh/claude-markdown-updates branch from a5f206f to 398c757 Compare October 24, 2025 14:13

fix: remove newapi example

b1539f0

jaaydenh merged commit 7bad7e3 into main Oct 24, 2025
24 checks passed

jaaydenh deleted the jaaydenh/claude-markdown-updates branch October 24, 2025 15:05

github-actions Bot locked and limited conversation to collaborators Oct 24, 2025

		- NEVER use implementation details in names (e.g., "ZodValidator", "MCPWrapper", "JSONParser")
		- NEVER use temporal/historical context in names (e.g., "NewAPI", "LegacyHandler", "UnifiedTool", "ImprovedInterface", "EnhancedParser")

	YOU MUST NEVER fix a symptom or add a workaround instead of finding a root cause, even if it is faster.
	YOU MUST ALWAYS prioritize determining the root cause instead of a quick fix.

		@.cursorrules
		@README.md

Conversation

jaaydenh commented Oct 23, 2025

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!

Choose a reason for hiding this comment

Uh oh!

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!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

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!

mafredri 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!

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!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants