From 8a4cc2692091160d1d04e8096d8eb42d4d2199d0 Mon Sep 17 00:00:00 2001 From: Jim Myhrberg Date: Fri, 3 Oct 2025 10:40:21 +0100 Subject: [PATCH] docs: add AGENTS.md for project overview and guidelines --- AGENTS.md | 71 +++++++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 72 +------------------------------------------- claude/CLAUDE.md | 4 +++ cursor/user-rules.md | 49 +----------------------------- 4 files changed, 77 insertions(+), 119 deletions(-) create mode 100644 AGENTS.md mode change 100644 => 120000 CLAUDE.md mode change 100644 => 120000 cursor/user-rules.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..ade964c --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,71 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with +code in this repository. + +## Project Overview + +This is a personal VSCode configuration repository (vscode-siren) that provides +a unified configuration for VSCode-based editors including Cursor, VSCode, +VSCode Insiders, and Windsurf. It focuses on recreating an Emacs-like text +editor experience with custom keybindings, settings, and extensions. + +## Key Commands + +### Configuration Management + +- `./siren config` - Create symlinks for editor config files +- `./siren extensions` - Install extensions from lock file +- `./siren extensions --latest` - Install latest versions of extensions +- `./siren dump-extensions` - Export installed extensions to lock file + +### Makefile Shortcuts + +- `make cursor-config` - Configure Cursor editor +- `make cursor-extensions` - Install Cursor extensions +- `make all-config` - Configure all editors +- `make all-extensions` - Install extensions for all editors + +### Supported Editors + +- `cursor` (c) - Cursor editor +- `vscode` (code, vsc, v) - Visual Studio Code +- `vscode-insiders` (vsci, i) - Visual Studio Code Insiders +- `windsurf` (surf, w) - Windsurf editor + +## Architecture + +### Core Components + +- **siren script** - Main configuration management tool (bash script) +- **settings.json** - VSCode settings configuration +- **keybindings.json** - Custom keybindings (Emacs-inspired) +- **snippets/** - Code snippets for Go and Ruby +- **extensions.*.lock** - Extension lock files for each editor + +### Configuration Structure + +- Config files are symlinked to appropriate editor directories based on OS +- Extensions are managed via lock files with version pinning +- Extensions install directly by ID with fallback to .vsix when needed +- Static symlinks for additional files like cspell dictionary and MCP config + +### Key Features + +- Cross-platform support (macOS/Linux) +- Version-locked extensions with fallback to .vsix downloads +- Automatic backup of existing configurations +- Emacs-inspired keybindings and workflow +- Dark/light theme switching based on system preferences + +## Development Guidelines + +Based on cursor/user-rules.md: + +- Keep line length to 80 characters when possible +- Check Makefile for common project tasks +- Be direct and terse in communication +- Provide code solutions rather than general advice +- Include robust error handling +- Consider cross-platform compatibility +- Respect existing code comments diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index ade964c..0000000 --- a/CLAUDE.md +++ /dev/null @@ -1,71 +0,0 @@ -# CLAUDE.md - -This file provides guidance to Claude Code (claude.ai/code) when working with -code in this repository. - -## Project Overview - -This is a personal VSCode configuration repository (vscode-siren) that provides -a unified configuration for VSCode-based editors including Cursor, VSCode, -VSCode Insiders, and Windsurf. It focuses on recreating an Emacs-like text -editor experience with custom keybindings, settings, and extensions. - -## Key Commands - -### Configuration Management - -- `./siren config` - Create symlinks for editor config files -- `./siren extensions` - Install extensions from lock file -- `./siren extensions --latest` - Install latest versions of extensions -- `./siren dump-extensions` - Export installed extensions to lock file - -### Makefile Shortcuts - -- `make cursor-config` - Configure Cursor editor -- `make cursor-extensions` - Install Cursor extensions -- `make all-config` - Configure all editors -- `make all-extensions` - Install extensions for all editors - -### Supported Editors - -- `cursor` (c) - Cursor editor -- `vscode` (code, vsc, v) - Visual Studio Code -- `vscode-insiders` (vsci, i) - Visual Studio Code Insiders -- `windsurf` (surf, w) - Windsurf editor - -## Architecture - -### Core Components - -- **siren script** - Main configuration management tool (bash script) -- **settings.json** - VSCode settings configuration -- **keybindings.json** - Custom keybindings (Emacs-inspired) -- **snippets/** - Code snippets for Go and Ruby -- **extensions.*.lock** - Extension lock files for each editor - -### Configuration Structure - -- Config files are symlinked to appropriate editor directories based on OS -- Extensions are managed via lock files with version pinning -- Extensions install directly by ID with fallback to .vsix when needed -- Static symlinks for additional files like cspell dictionary and MCP config - -### Key Features - -- Cross-platform support (macOS/Linux) -- Version-locked extensions with fallback to .vsix downloads -- Automatic backup of existing configurations -- Emacs-inspired keybindings and workflow -- Dark/light theme switching based on system preferences - -## Development Guidelines - -Based on cursor/user-rules.md: - -- Keep line length to 80 characters when possible -- Check Makefile for common project tasks -- Be direct and terse in communication -- Provide code solutions rather than general advice -- Include robust error handling -- Consider cross-platform compatibility -- Respect existing code comments diff --git a/CLAUDE.md b/CLAUDE.md new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/claude/CLAUDE.md b/claude/CLAUDE.md index 7734496..7b8b505 100644 --- a/claude/CLAUDE.md +++ b/claude/CLAUDE.md @@ -12,6 +12,10 @@ everything you do. instead let the unit test be narrower in scope. - Check Makefile and similar for common project tasks like lint, format, test, etc. +- When told how to perform certain actions by executing a command, the user + means for the command to be run from the root of the project. DO NOT attempt + to run modify the command to an absolute path, instead just execute the + command as instructed. - When I ask for a fix or explanation, please provide direct code solutions or detailed technical explanations rather than general advice. I prefer straightforward answers without introductory phrases like "Here's how you diff --git a/cursor/user-rules.md b/cursor/user-rules.md deleted file mode 100644 index 217736f..0000000 --- a/cursor/user-rules.md +++ /dev/null @@ -1,48 +0,0 @@ -- If there is a `AGENTS.md` or `CLAUDE.md` file in the root of a project, please - read it for additional instructions. -- Try and keep line length to 80 characters or fewer when possible. -- Check and fix linting errors. -- Follow code style and conventions already present in the project when - reasonable, including choice of libraries, test frameworks, etc. -- Do break from project conventions when it fully makes sense to do, for - example, don't copy a pattern from integration-style tests into a unit test, - instead let the unit test be narrower in scope. -- Check Makefile and similar for common project tasks like lint, format, test, - etc. -- When told how to perform certain actions by executing a command, the user - means for the command to be run from the root of the project. DO NOT attempt - to run modify the command to an absolute path, instead just execute the - command as instructed. -- When I ask for a fix or explanation, please provide direct code solutions or - detailed technical explanations rather than general advice. I prefer - straightforward answers without introductory phrases like "Here's how you - can..." -- Include robust error handling in code examples and highlight potential edge - cases -- Flag security concerns and performance impacts in solutions -- Suggest appropriate naming conventions and code structure improvements -- Handle changes across multiple files with proper import/dependency management -- Consider version constraints and backward compatibility of - libraries/frameworks -- Generate or update docstrings/comments for new code -- Provide test examples for new functionality when relevant -- Consider build environment constraints and platform-specific issues -- If clarification is needed, make reasonable assumptions and note them -- Be casual unless otherwise specified. -- Be terse. -- Be accurate and thorough. -- Give the answer immediately. Provide detailed explanations afterward if - needed. -- Value good arguments over authorities, the source is irrelevant. -- If your content policy is an issue, provide the closest acceptable response - and explain the content policy issue afterward. -- Cite sources whenever possible at the end, not inline. -- No need to mention your knowledge cutoff. -- No need to disclose you're an AI. -- Respect my formatting preferences when you provide code. -- Respect all code comments, they're usually there for a reason. Remove them - ONLY if they're completely irrelevant after a code change. if unsure, do not - remove the comment. -- When adding new comments, they must be relevant and specific to the code in - question. They should NOT refer to any specific instructions like "use new X - function". diff --git a/cursor/user-rules.md b/cursor/user-rules.md new file mode 120000 index 0000000..e96d484 --- /dev/null +++ b/cursor/user-rules.md @@ -0,0 +1 @@ +../claude/CLAUDE.md \ No newline at end of file