When working on PRs, Claude Code was sometimes force pushing to
branches. This adds simple git workflow guidelines that emphasize proper
branch checkout and avoiding force pushes.
## Changes
Added git workflow section to `CLAUDE.md`, `AGENTS.md`, and
`.claude/docs/WORKFLOWS.md` with:
- Instructions to fetch, checkout, and pull before working on PR
branches
- Note to avoid `git push --force` unless explicitly requested
## Examples of force push behavior
Observed in recent PRs:
- PR #21148: 7 commits including merge commit from iterative changes
- PR #21150: 9 commits with multiple documentation iterations
- PR #21182: 4 commits with iterative fixes
- Force update on `feat/add-tasks-template-flag` branch:
`9bf7980b9...f98cf44f7`
The guidelines now make it clear to check out branches properly and push
normally.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
The _redirects file format is used by Netlify and Cloudflare Pages, but
coder.com runs on Vercel with Next.js. Redirects for coder.com/docs must
be configured in the coder/coder.com repository redirects.json file.
This file was never functional and caused confusion when renaming docs.
Co-authored-by: blink-so[bot] <211532188+blink-so[bot]@users.noreply.github.com>
## Summary
This PR addresses David's review comments from PR #21153 to improve the
Documentation Style Guide.
## Changes
- **Research section**: Updated to focus on reading "recent
documentation" instead of "10+ similar pages" - more practical guidance
- **Premium Feature Callout**: Clarified that the manifest.json badge
addition should happen in `docs/manifest.json`
- **Screenshot Guidelines**: Added context that this is for when
screenshots "don't exist yet", making it clearer this is a temporary
measure
- **Tabs documentation**: Expanded explanation to clarify when tabs are
appropriate (parallel content paths)
- **Coder registry**: Added mention of referencing Coder registry URLs
for cross-linking to external Coder resources
All changes maintain the existing documentation structure while
improving clarity and specificity based on review feedback.
Refs #21153🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
Adds a style guide documenting PR description patterns observed in the
Coder repository. This guide is intended for AI agents to reference when
creating PRs, ensuring consistency with project conventions.
The guide covers title format (Conventional Commits), description
structure (default concise vs. complex structured), what to include
(links, performance context, warnings), and what to avoid (test plans,
benefits sections). Includes examples from recent merged PRs
demonstrating each pattern.
Placed in `.claude/docs/` alongside other agent-specific documentation
(WORKFLOWS.md, ARCHITECTURE.md, etc.) rather than in the main
contributing docs, as this is primarily for automated tooling reference.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
Adds a comprehensive documentation style guide in
`.claude/docs/DOCS_STYLE_GUIDE.md` documenting patterns observed across
Coder's existing documentation. This guide is intended for AI agents to
reference when writing documentation, ensuring consistency with project
conventions.
The guide covers research requirements (code verification, permissions
model, UI thresholds), document structure (titles, premium callouts,
overview sections), image usage (placement, captions, screenshot-driven
organization), content organization, writing style, code examples,
accuracy standards (specific numbers, permission actions, API
endpoints), manifest requirements, and proactive documentation
approaches.
Placed in `.claude/docs/` alongside other agent-specific documentation
(WORKFLOWS.md, ARCHITECTURE.md, etc.) and imported in CLAUDE.md to
ensure it's automatically loaded into context for documentation work.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
Replace `.cursorrules` with symlink to `AGENTS.md` to establish a single
authoritative document for AI agent guidelines.
Extract architectural documentation from `.cursorrules` into
`.claude/docs/ARCHITECTURE.md` for reference material.
This ensures all AI agents (Claude, Cursor, etc.) use the same
guidelines without duplication.
---
🤖 This change was written by Claude Sonnet 4.5 Thinking using
[mux](https://github.com/coder/mux) and reviewed by a human 🏂
# Organize Development Documentation into Separate Files
This PR reorganizes the development documentation by splitting the monolithic CLAUDE.md file into multiple focused documents. The main file now provides a concise overview with essential commands and critical patterns, while importing detailed content from specialized guides.
Key improvements:
- Created separate documentation files for specific domains:
- Database development patterns
- OAuth2 implementation guidelines
- Testing best practices
- Troubleshooting common issues
- Development workflows and guidelines
- Restructured the main CLAUDE.md to be more scannable with improved formatting
- Added quick-reference tables for common commands
- Maintained all existing content while making it more accessible
- Highlighted critical patterns that must be followed
This organization makes the documentation more maintainable and easier to navigate, allowing developers to quickly find relevant information for their specific tasks.
Ben Potter