acidvegas/project_rules
1
Fork 1
Code Activity

Remove deprecated rules for AI behavior, directory structure, documentation, environment variables, file headers, gitignore, license, Python examples, functions, general practices, imports, memory handling, and style. Consolidate project rules into README.md for clarity and accessibility.

Browse Source
This commit is contained in:
Dionysus
2026-04-12 01:01:18 -04:00
parent 103c5b5896
commit a7b4e74a35
25 changed files with 945 additions and 582 deletions
Download Patch File Download Diff File Expand all files Collapse all files

63
.cursor/rules/documentation.mdc
View File

@@ -1,63 +0,0 @@
---
description: "Documentation standards for README.md files with proper structure and content"
alwaysApply: true
---
## Writing Style
- Use a clear, direct, human tone. Avoid hyper-intelligent language that sounds AI generated.
- Never use emojis or the `—` character in any comments, code, or README files.
- For controversial projects *(malicious POCs, recon/intel scraping, spam/flood tools)*, include a disclaimer stating the tool is for testing purposes only, to be used with legal permission or on your own systems.
- Keep markdown tables compact with minimal spacing. Align columns with only 1 space after the longest item, avoiding excessive padding.
- Avoid making README files just a bunch of lists in markdown, speak in paragraphs. You may use lists when it makes sense.
## Structure
Every `README.md` should follow this structure:
### Project Title & Description
Start with the project name as an H1 heading, followed by 1-3 concise paragraphs explaining what the project does.
### Table of Contents
Include a clickable table of contents with links to each major section.
### Requirements
List all dependencies with links:
- Software dependencies *(Python, Docker, etc)*
- PyPI packages *(with links to PyPI)*
- System packages or other tools
###### System Recommendations *(optional)*
- Recommended RAM
- Recommended disk space
- Any other system requirements
### Setup
Provide clear installation instructions:
- Package manager installation *(pip, npm, etc)*
- Manual installation with `git clone`
- Running setup scripts
- Environment variable configuration *(use tables for `.env` variables)*
- Any additional configuration steps
### Usage
Explain how to run the project:
- Basic usage examples
- CLI arguments *(use tables for clarity)*
- Configuration options
- Example commands
### Footer
Always end with the mirrors footer:
```
---
###### Mirrors: [acid.vegas](https://git.acid.vegas/) • [SuperNETs](https://git.supernets.org/acidvegas/) • [GitHub](https://github.com/acidvegas/) • [GitLab](https://gitlab.com/acidvegas/) • [Codeberg](https://codeberg.org/acidvegas/)
```

38
.cursor/rules/env.mdc
View File

@@ -1,38 +0,0 @@
---
description: "Environment variables and .env file configuration management for Bash and Python"
alwaysApply: true
---
Always create an `.env.example` file for any project that uses `.env` files.
## Bash
Basic one-liner example to prefix a bash script to require & load a local `.env` file:
```bash
[ -f .env ] && source .env || { echo "error: missing .env file" && exit 1 }
```
## Python
Here is an example of how most `config.py` files will look:
```python
import os
# Load .env if it exists
if os.path.exists('.env'):
try:
from dotenv import load_dotenv
except ImportError:
raise ImportError('missing python-dotenv library (pip install python-dotenv)')
else:
load_dotenv()
# Authentication settings
ADMIN_USERNAME = os.getenv('ADMIN_USERNAME', 'admin') # Has a default if undefined
ADMIN_PASSWORD = os.environ['API_KEY'] # Required
```
**Note:** This example makes the `.env` file itself optional, as environment variables may be set externally, via `systemd`, `docker`, etc.

12
.cursor/rules/gitignore.mdc
View File

@@ -1,12 +0,0 @@
---
description: "Gitignore standards for excluding sensitive and generated files from version control"
alwaysApply: true
---
## Example of files to ignore:
- Sensitive settings or keys: `.env`
- Logs or temporary files: `logs/`
- Python cache: `__pycache__/`
Only include what is truly needed to be excluded from version control so we can keep secrets, logs, & auto-generated files out of Git.

42
.cursor/rules/python-functions.mdc
View File

@@ -1,42 +0,0 @@
---
description: "Python function naming, structure, and documentation standards"
alwaysApply: true
---
## Function Conventions
- All functions should be in ABC order, seperated by 2 blank lines.
- Use `snake_case` for functions & use `PascalCase` for classes.
## Type Hints
- Use type hints on all function arguments & return *(`def example(name: str) -> bool:`)*
- **Never** use `-> None:` as a return hint.
- Do not use `from typing import ...`, it makes type hints & return hints looks hideous.
## Docstrings
All functions should have a docstring matching the formats below:
###### Functions with arguments:
```python
def example_function(name: str, age: int) -> bool:
'''
This is a short & simple to the point description of the function.
:param name: This is a small description of the name argument
:param age: This is a small description of the age argument
'''
```
###### Functions without arguments:
```python
def simple_function():
'''This is a short & simple to the point description of the function.```
```
- 1 blank line after a functions docstring line.

16
.cursor/rules/python-general.mdc
View File

@@ -1,16 +0,0 @@
---
description: "General Python coding standards and best practices"
alwaysApply: true
---
- Prefer a modular asynchronous design with `asyncio`.
- Comments in code should be informative for explaining the flow of the code.
- Inline comments are only for small clarifications, avoid over-commenting.
- Never do redundant things using `subprocess` that can be done in Python code instead.
- Follow Single Responsibility Principle.
- Follow DRY (Don't Repeat Yoursekf) Principle.

54
.cursor/rules/python-imports.mdc
View File

@@ -1,54 +0,0 @@
---
description: "Python import organization and structuring standards"
alwaysApply: true
---
Prefer standard Python libraries before PyPI libraries.
Imports always belong at the top, never in the middle of code *(exception made for imports inside of `if __name__ == '__main__:')*
Avoid using the `requests` library if possible in favor of `aiohttp` or `urllib.request`.
## Import Order
Imports are done in 3 categories: **Standard Library** → **PyPI Libraries** → **Local Project Imports**
- Each category is separated by a blank line, with 2 blank lines after the last import.
- All imports within each section are in ABC order
- When using `from x import y, z`, the imported items *(y, z)* are also in ABC order
### 1. Standard Library
Direct imports first, then a blank line, then `from x import y` imports:
```python
import random
import sys
import time
from datetime import datetime, timezone
```
### 2. PyPI Libraries
All PyPI imports must use the try/except format:
```python
try:
import aiohttp
except ImportError:
raise ImportError('missing aiohttp library (pip install aiohttp)')
try:
import requests
except ImportError:
raise ImportError('missing requests library (pip install requests)')
```
### 3. Local Project Imports
```python
from core import config, ftp, irc, utils
from debug import get_ip, logger
```

24
.cursor/rules/python-style.mdc
View File

@@ -1,24 +0,0 @@
---
description: "Python code alignment and styling standards"
alwaysApply: true
---
- Use tabs for indentation, not spaces.
- Always preffer using single quotes & not double quotes.
- Vertically align assignments, dicts, parameters, comments, etc for readability, example:
```python
self.chunk_max = args.chunk_max * 1024 * 1024 # MB
self.chunk_size = args.chunk_size
self.es_index = args.index
```
**Note:** Align columns with only 1 space after the longest item, avoiding excessive padding.
- Use `_` inside of large integers *(`250_000` instead of `250000`)* for readability.
- Inline comments should only have a single space before the `#`, unless vertically aligning.
- Always use 3 blank lines before `if __name__ == '__main__'.

572
CLAUDE.md Normal file
View File

@@ -0,0 +1,572 @@
## AI BEHAVIOR
This is our rule for general AI behavior including how an LLM should and should not react or handle operations.
1. **Verify Information**: Always verify information before presenting it. Do not make assumptions or speculate without clear evidence.
2. **File-by-File Changes**: Make changes file by file & give me a chance to spot mistakes.
3. **No Apologies**: Never use apologies.
4. **No Understanding Feedback**: Avoid giving feedback about understanding in comments or documentation.
5. **No Summaries**: Don't summarize changes made.
6. **No Inventions**: Don't invent changes other than what's explicitly requested.
7. **No Unnecessary Updates**: Don't suggest updates or changes to files when there are no actual modifications needed.
8. **Clarify Before Acting**: Do not make changes or proceed with any action unless you are 100% clear on the user's intentions and meaning. Ask for clarification if there is any ambiguity.
9. **Use Tabs for Indentation**: Always use tabs instead of spaces for indentation in code.
10. **No Sudo Access**: Never use `sudo` commands. If a command or script requires `sudo` or system package installation (like `apt install`), provide the command to the user and instruct them to run it manually.
---
## AI Response Optimization
This is our rule for how the AI should respond in chat conversations. Use concise, information-dense phrasing. Prefer shorter word choices when meaning is clear.
**Important:** This rule applies only to LLM chat responses to the user. It does NOT apply to:
- README files or project documentation
- Code comments
- Markdown files or other written content
Chat in this concise style normally unless the user requests a more verbose response.
Avoid unnecessary repetition or filler language.
### Examples
```
Verbose: "In the event that you need to…"
Optimized: "If you need to…"
```
```
Verbose: "In accordance with"
Optimized: "Per" or "Following"
```
```
Verbose: "Due to the fact that"
Optimized: "Because"
```
```
Verbose: "At this point in time"
Optimized: "Now"
```
```
Verbose: "Make a decision regarding"
Optimized: "Decide"
```
```
Verbose: "In order to achieve"
Optimized: "To achieve"
```
```
Verbose: "Has the ability to"
Optimized: "Can"
```
```
Verbose: "It is important to note that"
Optimized: "Note that" or just omit
```
```
Verbose: "For the purpose of"
Optimized: "For" or "To"
```
```
Verbose: "A number of"
Optimized: "Several" or "Some"
```
---
## DIRECTORY STRUCTURE
This is our rules for project directory structures. This serves as an example for guidance on how a projects files should be organized.
###### Example project directory tree:
```
company_project_scraper/
.env
.env.example
.gitignore
assets/
company_metadata.json
employees.sql
core/
config.py
ftp.py
irc.py
events.py
utils.py
logs/
projectname_yyyy-mm-dd.log
Dockerfile
LICENSE
main.py
requirements.txt
README.md
setup.sh
test.py
```
###### Files descriptions:
- `.env` — secret environment variables, keep out of version control
- `.env.example` — template showing all required environment variables
- `.gitignore` — files and directories to exclude from Git
- `assets/` — static or downloaded data, e.g., CSVs, JSONs, SQL files; can be gitignored if large or generated locally
- `core/` — reusable Python modules *(config, FTP, IRC, events, utility functions)*
- `logs/` — application log files, typically dated
- `Dockerfile` — container setup instructions
- `LICENSE` — project license
- `main.py` — main script that runs the project
- `requirements.txt` — Python dependencies
- `README.md` — project overview and instructions
- `setup.sh` — setup script for OS packages, pip dependencies, Docker, etc.
- `test.py`— Unit testing or proof of example script to validate functionality where needed.
Not all of these files are required for every project, this is just an example as guidance.
All `.sh` bash files should be `chmod +x` .
---
## LICENSE
This is our rules for the LICENSE file that all projects will include.
###### LICENSE file contents:
```
ISC License
Copyright (c) {YYYY}, acidvegas <acid.vegas@acid.vegas>
Permission to use, copy, modify, and/or distribute this software for any
purpose with or without fee is hereby granted, provided that the above
copyright notice and this permission notice appear in all copies.
THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
```
**Note:** `{YYYY}` is replaced by the current year *(example: `2026`)*
---
## FILE HEADINGS
This is our rules for the file headings added to most files in the project directory.
### Use proper shebangs:
| Language | Shebang |
| -------- | ------------------------ |
| Bash | `#!/usr/bin/env bash` |
| Python | `#!/usr/bin/env python3` |
### Project name, credits, & file reference:
Any file that supports comments must include the following header comments at the top:
```text
# Project Name Here - Developed by acidvegas in Python (https://git.acid.vegas)
# project_dir_name/filename.ext
```
This includes Python, Bash, Dockerfile, `.env`, `.ini`, C, SQL, or any other text-based files, NOT markdown files.
This is placed immediately after the shebang, if one exists.
Use language specific comment prefixes if applicable like how `C` programming uses `//` for comments.
---
## GITIGNORE
This is our rules for creating and managing a `.gitignore` for a project to hide files you don't want in version control.
###### Examples:
- Sensitive settings or keys: `.env`
- Logs or temporary files: `logs/`
- Python cache: `__pycache__/`
Only include what is truly needed, this is not a file to over fluff.
Goal: keep secrets, logs, and auto-generated files out of Git.
---
## README
This is our rules for creating and managing a projects `README.md` file.
### Template
```
# Project Name
1–3 concise paragraphs explaining what the project does.
## Table of Contents
Clickable table of contents
## Requirements
- [Python](https://python.org)
- [request](https://pypi.org/project/requests)
- [Terraform](https://terraform.com)
###### System Recommendations
- 2GB Ram
- 50gb Disk
## Setup
pip install -r requirements or pip install [repo name]
or manual with git clone seup.sh etc.
or running setup.sh
talk about .env or settings to changeuse a table to give detail able them.
## Usage
how to run it the cli arguments in a table, etc
---
###### Mirrors: [SuperNETs](https://git.supernets.org/acidvegas/) • [GitHub](https://github.com/acidvegas/) • [GitLab](https://gitlab.com/acidvegas/) • [Codeberg](https://codeberg.org/acidvegas/)
```
- Clear, direct, human tone, not hyper-intelligent language that is obviously AI generated.
- Never use emojis or the `—` character in any comments, code, or README files.
- Vertically align markdown tables based on the largest item in each column with only 1 space after it.
- Text in parentheses should be italicized using `*()* ` format in markdown.
- If a project is controversial, for example, to spam/flood something, a malicious proof of concept, or some kind of recon/intel data scraping, then include a disclaimer saying you are not liable, made for testing with legal permission or on your own servers.
---
## ENV
This is our rules for handling environment variables usage including requiring them, using them for sensitive settings, authentication, etc.
Create a `.env.example` file for any project that uses `.env` files. The example file will not be in `.gitignore`' and will serve as a template for whats expected in the`.env` file. Most people will do `cp .env.example .env` and then edit the `.env` to get started.
### Bash
Basic one-liner example to prefix a bash script to require and load a local `.env` file:
```bash
[ -f .env ] && source .env || { echo "error: missing .env file" && exit 1 }
```
Here is an example of doing an undefined environment variable fallback:
```bash
echo ${ADMIN_USERNAME:-admin}
```
### Python:
Here is an example of how most `config.py` files will look. This example makes the `.env` file itself optional as environment variables may be set externally, via `systemd`, `docker`, etc:
```python
import os
# Load .env if it exists
if os.path.exists('.env'):
try:
from dotenv import load_dotenv
except ImportError:
raise ImportError('missing python-dotenv library (pip install python-dotenv)')
else:
load_dotenv()
# Authentication settings
ADMIN_USERNAME = os.getenv('ADMIN_USERNAME', 'admin') # Has a default if undefined
ADMIN_PASSWORD = os.environ['API_KEY'] # Required
# Other settings
ENVIRONMENT = 'prod'
VERSION = '1.0.2b'
```
---
## PYTHON - General Guidelines
- Always use Python virtual environments (venvs) for all projects to ensure dependency isolation.
- Prefer standard Python libraries before third-party PyPI libraries.
- Comments in code should be informative for simply explaining the flow of the code in English.
- Inline comments are only for small clarifications, avoid over-commenting
- Prefer an asynchronous design with `asyncio`.
- Avoid using the `requests` library if possible. More often than not we will opt for `aiohttp` but there is almost always a standard library way to do anything `requstes` can do, meaning we don't have to depend on PyPI packages if we don't need to.
- Use `_` inside of large int's, like `250_000` instead of `250000` for readability.
- Avoid doing any of the following:
- pointless variables declared
- gigantic functions with too many lines of code
- functions with too many arguments
- adding un-necessary or un-asked for delays with `sleep`
- using `subprocess` or `os` for something redundant, that can be done in Python *(like `curl` or `wget`)*.
- When killing a Python process that was started by the LLM, always verify afterwards that the process was actually terminated.
- For Flask applications, use separate files for web assets: `index.html`, `style.css`, and `utils.js` instead of inline code.
---
## PYTHON - Import Organization
Imports are done categorically, in order, with a blank line between each category:
1. **Standard Library - direct imports**
```python
import random
import sys
import time
```
2. **Standard Library - `from x import y`**
```python
from datetime import datetime
```
3. **Third-Party PyPI Libraries**
- All PyPI imports must match this format:
```python
try:
import requests
except ImportError:
raise ImportError('missing requests library (pip install requests)')
```
4. **Local Project Imports**
```python
from core import config, ftp, irc, utils
```
- Imports always belong at the top, never in the middle of code. The only exception is ones found after `if __name__ == '__main__:'.
---
## PYTHON - Function Conventions
- Use a naming convention format like `def event_message():` rather than `def eventMessage():` or other styling types.
- All functions should be in ABC order.
- Use type hints on arguments and return *(`def example(name: str) -> bool:`)*
- **Never** use `-> None:` as a return hint.
- Do not use `from typing import ...`, it makes type hints and return hints looks hideous.
- All functions should have a docstring matching the formats below for functions with and without arguments:
### Functions with Arguments
```python
def example_function(name: str, age: int) -> bool:
'''
This is a simple to the point minimal function with arguments description in 1 line.
:param name: The customers name
:param age: The customers age
'''
```
### Functions without Arguments
```python
def simple_function():
'''This is a simple to the point minimal function description in 1 line.```
```
---
## PYTHON - Code Style & Alignment
- Use single quotes only, double quotes inside nested f-strings.
- Vertically align assignments, dicts, parameters, comments, etc for readability, example:
```python
self.chunk_max = args.chunk_max * 1024 * 1024 # MB
self.chunk_size = args.chunk_size
self.es_index = args.index
```
- Inline comments should only have a single space before the `#`, not 2 spaces.
- Three blank lines before `if __name__ == '__main__'.
- Two blank lines after the last import.
- 1 blank line after a functions docstring line.
- 2 blank lines in between every function.
---
## PYTHON - Memory-Safe Data Handling
When reading large files or fetching large amounts of data *(files, URLs, streams)*, process incrementally to avoid high memory usage:
- `yield` or async generators
- Read line by line or in chunks
Storing a massive amount of data in variables can yield high memory usage which may be avoidable in certain situations.
Apply only when applicable *(don't overcomplicate small data handling)*.
---
## PYTHON - Logging with APV
The [APV](https://pypi.org/project/apv/) library is preferred in all Python projects for logging. It wraps the standard logging library, allowing you to use `logging.info`, `logging.error`, `logging.debug`, `logging.warn`, `logging.fatal`, etc throughout the project without defining a `logger` variable.
### Setup Example
```python
import argparse
import apv
# Setup parser
parser = argparse.ArgumentParser()
parser.add_argument('-d', '--debug', action='store_true', help='Enable debug logging')
args = parser.parse_args()
# Setup logging via apv
if args.debug:
apv.setup_logging(level='DEBUG', log_to_disk=True, max_log_size=10*1024*1024, max_backups=5, log_file_name='application_log')
else:
apv.setup_logging(level='INFO')
```
### Usage Throughout Code
Once APV is initialized, use standard logging calls anywhere in your project:
```python
import logging
logging.info('Application started')
logging.debug('Debug information here')
logging.error('An error occurred')
logging.warn('Warning message')
logging.fatal('Critical error')
```
---
## PYTHON - Project Code Examples
### Example main.py
```python
import asyncio
import logging
async def main():
'''Main asynchronous entrypoint of the application'''
# Start the main loop
while True:
try:
pass # Your async code goes here
except KeyboardInterrupt:
logging.debug('Keyboard interrupt detected, closing connections & exiting...')
# Exit the matrix
break
except Exception as e:
logging.fatal(f'Critical connection error: {str(e)}')
finally:
await asyncio.sleep(15) # Delay before trying restarting the loop
if __name__ == '__main__':
import argparse
import apv
# Setup parser
parser = argparse.ArgumentParser()
parser.add_argument('-d', '--debug', action='store_true', help='Enable debug logging')
args = parser.parse_args()
# Setup logging via apv
if args.debug:
apv.setup_logging(level='DEBUG', log_to_disk=True, max_log_size=100*1024*1024, max_backups=5, log_file_name='application_log')
else:
apv.setup_logging(level='INFO')
logging.info('Application Name has started')
# Run the async main
asyncio.run(main())
```
---
### Example setup.sh
```bash
# Load environment variables
[ -f .env ] && source .env || { echo "Error: .env file not found"; exit 1; }
# Set xtrace, exit on error, & verbose mode (after loading environment variables)
set -xev
# Remove existing docker container if it exists
docker rm -f container_name 2>/dev/null || true
# Build the Docker image
docker build -t container_name .
# Run the Docker container with environment variables
docker run -d --name container_name \
--restart unless-stopped \
--network host \
--hostname $(hostname) \
-v /etc/os-release:/etc/os-release:ro \
-e ES_HOST="${ES_HOST}" \
-e ES_USERNAME="${ES_USERNAME}" \
-e ES_PASSWORD="${ES_PASSWORD}" \
-e ES_API_KEY="${ES_API_KEY}" \
container_name
```
### Example Dockerfile
```Dockerfile
# Use the slim version of the Python image
FROM python:3-slim
# Create the app directory
RUN mkdir -p /app
# Set up in the application directory
WORKDIR /app
# Copy python requirements file
COPY requirements.txt .
# Set up Python environment and install dependencies
RUN python3 -m pip install --upgrade pip && python3 -m pip install --no-cache-dir --only-binary :all: -r requirements.txt --upgrade
# Cleanup the python requirements file (not needed at runtime)
RUN rm requirements.txt
# Copy only the necessary application files
COPY . .
# Create entrypoint script with restart capability
RUN printf '#!/bin/sh\ncd /app\nwhile true; do sleep 10 && python3 main.py -d; done' > /app/entrypoint.sh && chmod +x /app/entrypoint.sh
# Set the entrypoint
ENTRYPOINT ["/app/entrypoint.sh"]
```

317
README.md
View File

@@ -1,300 +1,49 @@
# Rules
# Project Rules for Claude Code
Rules provide system-level instructions to Agent. They bundle prompts, scripts, and more together, making it easy to manage and share workflows across your team.
This repository contains coding standards, style guidelines, and best practices for use with Claude Code.
Cursor supports three types of rules:
## Usage
## Rule Types
### Merging Rules
### Project Rules
Stored in `.cursor/rules`, version-controlled and scoped to your codebase.
### User Rules
Global to your Cursor environment. Used by Agent **(Chat)**.
### AGENTS.md
Agent instructions in markdown format. Simple alternative to `.cursor/rules`.
## How rules work
Large language models don't retain memory between completions. Rules provide persistent, reusable context at the prompt level.
When applied, rule contents are included at the start of the model context. This gives the AI consistent guidance for generating code, interpreting edits, or helping with workflows.
## Project rules
Project rules live in `.cursor/rules`. Each rule is a folder containing a `RULE.md` file and is version-controlled. They are scoped using path patterns, invoked manually, or included based on relevance.
Use project rules to:
- Encode domain-specific knowledge about your codebase
- Automate project-specific workflows or templates
- Standardize style or architecture decisions
### Rule folder structure
Each rule folder can contain:
- **`RULE.md`** — The main rule file with frontmatter metadata and instructions
- **Scripts and prompts** — Additional files referenced by the rule
Run the merge script to combine all rules into a single file:
```bash
.cursor/rules/
my-rule/
RULE.md # Main rule file
scripts/ # Helper scripts **(optional)**
./merge
```
### Rule anatomy
This creates `RULES.md` with all rules separated by `---`.
Each rule is a folder containing a `RULE.md` file with frontmatter metadata and content. Control how rules are applied from the type dropdown which changes properties `description`, `globs`, `alwaysApply`.
### Using with Claude Code
| Rule Type | Description |
| :--- | :--- |
| `Always Apply` | Apply to every chat session |
| `Apply Intelligently` | When Agent decides it's relevant based on description |
| `Apply to Specific Files` | When file matches a specified pattern |
| `Apply Manually` | When @-mentioned in chat **(e.g., `@my-rule`)** |
Copy the contents of `RULES.md` and paste it into Claude Code's system prompt or custom instructions. These rules will guide Claude's behavior across all coding sessions.
```md
---
globs:
alwaysApply: false
---
## Rules Overview
- Use our internal RPC pattern when defining services
- Always use snake_case for service names.
| File | Description |
| --------------------------- | ------------------------------------------------ |
| `00-AI_BEHAVIOR.md` | General AI behavior and operational guidelines |
| `01-OPTIMIZED_RESPOPNSE.md` | Response optimization for concise communication |
| `02-DIRECTORY_STRUCTURE.md` | Project directory organization standards |
| `03-LICENSE.md` | ISC license template |
| `04-FILE_HEADINGS.md` | File header and shebang conventions |
| `05-GITIGNORE.md` | Git ignore file guidelines |
| `06-README.md` | README documentation standards |
| `07-ENV.md` | Environment variable handling |
| `08-PYTHON-GENERAL.md` | General Python guidelines |
| `09-PYTHON-IMPORTS.md` | Python import organization |
| `10-PYTHON-FUNCTIONS.md` | Python function conventions |
| `11-PYTHON-STYLE.md` | Python code style and alignment |
| `12-PYTHON-MEMORY.md` | Memory-safe data handling |
| `13-PYTHON-LOGGING.md` | Logging with APV library |
| `14-PYTHON-PROJECT.md` | Python project examples |
@service-template.ts
```
## Editing Rules
### Creating a rule
Rules are organized in separate markdown files in the `PROJECT_RULES/` directory for easy maintenance. After making changes, run `./merge.sh` to regenerate the merged file.
Create rules using the `New Cursor Rule` command or going to `Cursor Settings > Rules, Commands`. This creates a new rule folder in `.cursor/rules`. From settings you can see all rules and their status.
## Structure
## Best practices
Good rules are focused, actionable, and scoped.
- Keep rules under 500 lines
- Split large rules into multiple, composable rules
- Provide concrete examples or referenced files
- Avoid vague guidance. Write rules like clear internal docs
- Reuse rules when repeating prompts in chat
## RULE.md file format
The `RULE.md` file is a markdown file with frontmatter metadata and content. The frontmatter metadata is used to control how the rule is applied. The content is the rule itself.
```md
---
description: "This rule provides standards for frontend components and API validation"
alwaysApply: false
---
...rest of the rule content
```
If alwaysApply is true, the rule will be applied to every chat session. Otherwise, the description of the rule will be presented to the Cursor Agent to decide if it should be applied.
## Examples
### Standards for frontend components and API validation
This rule provides standards for frontend components:
When working in components directory:
- Always use Tailwind for styling
- Use Framer Motion for animations
- Follow component naming conventions
This rule enforces validation for API endpoints:
In API directory:
- Use zod for all validation
- Define return types with zod schemas
- Export types generated from schemas
### Templates for Express services and React components
This rule provides a template for Express services:
Use this template when creating Express service:
- Follow RESTful principles
- Include error handling middleware
- Set up proper logging
@express-service-template.ts
This rule defines React component structure:
React components should follow this layout:
- Props interface at top
- Component as named export
- Styles at bottom
@component-template.tsx
### Automating development workflows and documentation generation
This rule automates app analysis:
When asked to analyze the app:
1. Run dev server with `npm run dev`
2. Fetch logs from console
3. Suggest performance improvements
This rule helps generate documentation:
Help draft documentation by:
- Extracting code comments
- Analyzing README.md
- Generating markdown documentation
### Adding a new setting in Cursor
First create a property to toggle in `@reactiveStorageTypes.ts`.
Add default value in `INIT_APPLICATION_USER_PERSISTENT_STORAGE` in `@reactiveStorageService.tsx`.
For beta features, add toggle in `@settingsBetaTab.tsx`, otherwise add in `@settingsGeneralTab.tsx`. Toggles can be added as `<SettingsSubSection>` for general checkboxes. Look at the rest of the file for examples.
```jsx
<SettingsSubSection
label="Your feature name"
description="Your feature description"
value={
vsContext.reactiveStorageService.applicationUserPersistentStorage
.myNewProperty ?? false
}
onChange={(newVal) => {
vsContext.reactiveStorageService.setApplicationUserPersistentStorage(
"myNewProperty",
newVal,
);
}}
/>
```
To use in the app, import reactiveStorageService and use the property:
```js
const flagIsEnabled =
vsContext.reactiveStorageService.applicationUserPersistentStorage
.myNewProperty;
```
Examples are available from providers and frameworks. Community-contributed rules are found across crowdsourced collections and repositories online.
## Importing Rules
You can import rules from external sources to reuse existing configurations or bring in rules from other tools.
### Remote rules **(via GitHub)**
Import rules directly from any GitHub repository you have access to—public or private.
1. Open **Cursor Settings → Rules, Commands**
2. Click `+ Add Rule` next to `Project Rules`, then select Remote Rule **(Github)**
3. Paste the GitHub repository URL containing the rule
4. Cursor will pull and sync the rule into your project
Imported rules stay synced with their source repository, so updates to the remote rule are automatically reflected in your project.
### Agent Skills
Cursor can load rules from Agent Skills, an open standard for extending AI agents with specialized capabilities. These imported skills are always applied as agent-decided rules, meaning Cursor determines when they are relevant based on context.
To enable or disable Agent Skills:
1. Open **Cursor Settings → Rules**
2. Find the **Import Settings** section
3. Toggle **Agent Skills** on or off
> **Note:** Agent Skills are treated as agent-decided rules and cannot be configured as always-apply or manual rules.
## AGENTS.md
`AGENTS.md` is a simple markdown file for defining agent instructions. Place it in your project root as an alternative to `.cursor/rules` for straightforward use cases.
Unlike Project Rules, `AGENTS.md` is a plain markdown file without metadata or complex configurations. It's perfect for projects that need simple, readable instructions without the overhead of structured rules.
Cursor supports AGENTS.md in the project root and subdirectories.
```md
# Project Instructions
## Code Style
- Use TypeScript for all new files
- Prefer functional components in React
- Use snake_case for database columns
## Architecture
- Follow the repository pattern
- Keep business logic in service layers
```
### Nested AGENTS.md support
Nested `AGENTS.md` support in subdirectories is now available. You can place `AGENTS.md` files in any subdirectory of your project, and they will be automatically applied when working with files in that directory or its children.
This allows for more granular control of agent instructions based on the area of your codebase you're working in:
```bash
project/
AGENTS.md # Global instructions
frontend/
AGENTS.md # Frontend-specific instructions
components/
AGENTS.md # Component-specific instructions
backend/
AGENTS.md # Backend-specific instructions
```
Instructions from nested `AGENTS.md` files are combined with parent directories, with more specific instructions taking precedence.
## User Rules
User Rules are global preferences defined in **Cursor Settings → Rules** that apply across all projects. They are used by Agent **(Chat)** and are perfect for setting preferred communication style or coding conventions:
```md
Please reply in a concise style. Avoid unnecessary repetition or filler language.
```
## Legacy Cursor Rules
### `.cursorrules`
The `.cursorrules` **(legacy)** file in your project root is still supported but **will be deprecated**. We recommend migrating to Project Rules or to `AGENTS.md`.
### `.mdc` cursor rules
As of 2.2, `.mdc` cursor rules will remain functional however all new rules will now be created as folders in `.cursor/rules`. This is to improve the readability and maintainability of rules.
## FAQ
### Why isn't my rule being applied?
Check the rule type. For `Apply Intelligently`, ensure a description is defined. For `Apply to Specific Files`, ensure the file pattern matches referenced files.
### Can rules reference other rules or files?
Yes. Use `@filename.ts` to include files in your rule's context. You can also @mention rules in chat to apply them manually.
### Can I create a rule from chat?
Yes, you can ask the agent to create a new rule for you.
### Do rules impact Cursor Tab or other AI features?
No. Rules do not impact Cursor Tab or other AI features.
### Do User Rules apply to Inline Edit **(Cmd/Ctrl+K)**?
No. User Rules are not applied to Inline Edit **(Cmd/Ctrl+K)**. They are only used by Agent **(Chat)**.
---
*Documentation sourced from: https://cursor.com/docs/context/rules*
- `PROJECT_RULES/` - Individual rule files
- `merge.sh` - Script to combine all rules
- `MERGED_RULES.md` - Combined rules file for Claude Code

13
.cursor/rules/ai-behavior.mdc → RULES/00-AI_BEHAVIOR.md
View File

@@ -1,7 +1,6 @@
---
description: "AI assistant behavior and response standards"
alwaysApply: true
---
## AI BEHAVIOR
This is our rule for general AI behavior including how an LLM should and should not react or handle operations.
1. **Verify Information**: Always verify information before presenting it. Do not make assumptions or speculate without clear evidence.
@@ -17,4 +16,8 @@ alwaysApply: true
7. **No Unnecessary Updates**: Don't suggest updates or changes to files when there are no actual modifications needed.
8. **Please reply in a concise style**: Avoid unnecessary repetition or filler language.
8. **Clarify Before Acting**: Do not make changes or proceed with any action unless you are 100% clear on the user's intentions and meaning. Ask for clarification if there is any ambiguity.
9. **Use Tabs for Indentation**: Always use tabs instead of spaces for indentation in code.
10. **No Sudo Access**: Never use `sudo` commands. If a command or script requires `sudo` or system package installation (like `apt install`), provide the command to the user and instruct them to run it manually.

64
RULES/01-OPTIMIZED_RESPOPNSE.md Normal file
View File

@@ -0,0 +1,64 @@
## AI Response Optimization
This is our rule for how the AI should respond in chat conversations. Use concise, information-dense phrasing. Prefer shorter word choices when meaning is clear.
**Important:** This rule applies only to LLM chat responses to the user. It does NOT apply to:
- README files or project documentation
- Code comments
- Markdown files or other written content
Chat in this concise style normally unless the user requests a more verbose response.
Avoid unnecessary repetition or filler language.
### Examples
```
Verbose: "In the event that you need to…"
Optimized: "If you need to…"
```
```
Verbose: "In accordance with"
Optimized: "Per" or "Following"
```
```
Verbose: "Due to the fact that"
Optimized: "Because"
```
```
Verbose: "At this point in time"
Optimized: "Now"
```
```
Verbose: "Make a decision regarding"
Optimized: "Decide"
```
```
Verbose: "In order to achieve"
Optimized: "To achieve"
```
```
Verbose: "Has the ability to"
Optimized: "Can"
```
```
Verbose: "It is important to note that"
Optimized: "Note that" or just omit
```
```
Verbose: "For the purpose of"
Optimized: "For" or "To"
```
```
Verbose: "A number of"
Optimized: "Several" or "Some"
```

23
.cursor/rules/directory-structure.mdc → RULES/02-DIRECTORY_STRUCTURE.md
View File

@@ -1,10 +1,8 @@
---
description: "Project directory structures and file organization standards"
alwaysApply: true
---
## DIRECTORY STRUCTURE
## Example project directory tree:
This is our rules for project directory structures. This serves as an example for guidance on how a projects files should be organized.
###### Example project directory tree:
```
company_project_scraper/
.env
@@ -30,13 +28,10 @@ company_project_scraper/
test.py
```
Not all of these files are required for every project, this is just an example as guidance.
#### Files descriptions:
###### Files descriptions:
- `.env` — secret environment variables, keep out of version control
- `.env.example` — template showing all required environment variables
- `.gitignore` — files & directories to exclude from Git
- `.gitignore` — files and directories to exclude from Git
- `assets/` — static or downloaded data, e.g., CSVs, JSONs, SQL files; can be gitignored if large or generated locally
- `core/` — reusable Python modules *(config, FTP, IRC, events, utility functions)*
- `logs/` — application log files, typically dated
@@ -44,6 +39,10 @@ Not all of these files are required for every project, this is just an example a
- `LICENSE` — project license
- `main.py` — main script that runs the project
- `requirements.txt` — Python dependencies
- `README.md` — project overview & instructions
- `README.md` — project overview and instructions
- `setup.sh` — setup script for OS packages, pip dependencies, Docker, etc.
- `test.py`— Unit testing or proof of example script to validate functionality where needed.
- `test.py`— Unit testing or proof of example script to validate functionality where needed.
Not all of these files are required for every project, this is just an example as guidance.
All `.sh` bash files should be `chmod +x` .

11
.cursor/rules/license.mdc → RULES/03-LICENSE.md
View File

@@ -1,9 +1,8 @@
---
description: "ISC license template standards for all projects"
alwaysApply: true
---
## LICENSE
## LICENSE file contents:
This is our rules for the LICENSE file that all projects will include.
###### LICENSE file contents:
```
ISC License
@@ -23,4 +22,4 @@ ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
```
**Note:** `{YYYY}` is replaced by the current year *(example: `2026`)*
**Note:** `{YYYY}` is replaced by the current year *(example: `2026`)*

17
.cursor/rules/file-headers.mdc → RULES/04-FILE_HEADINGS.md
View File

@@ -1,25 +1,24 @@
---
description: "File header standards including shebangs and project credits"
alwaysApply: true
---
## FILE HEADINGS
## Use proper shebangs:
This is our rules for the file headings added to most files in the project directory.
### Use proper shebangs:
| Language | Shebang |
| -------- | ------------------------ |
| Bash | `#!/usr/bin/env bash` |
| Python | `#!/usr/bin/env python3` |
### Project name, credits, & file reference:
## Project name, credits, & file reference:
Any file that supports comments must include the following header comments at the top:
Any text-based file that supports comments must include the following header comments at the top:
```
```text
# Project Name Here - Developed by acidvegas in Python (https://git.acid.vegas)
# project_dir_name/filename.ext
```
This includes Python, Bash, Dockerfile, `.env`, `.ini`, C, SQL, or any other text-based files, NOT markdown files.
This is placed immediately after the shebang, if one exists.
Use language specific comment prefixes if applicable like how `C` programming uses `//` for comments.

12
RULES/05-GITIGNORE.md Normal file
View File

@@ -0,0 +1,12 @@
## GITIGNORE
This is our rules for creating and managing a `.gitignore` for a project to hide files you don't want in version control.
###### Examples:
- Sensitive settings or keys: `.env`
- Logs or temporary files: `logs/`
- Python cache: `__pycache__/`
Only include what is truly needed, this is not a file to over fluff.
Goal: keep secrets, logs, and auto-generated files out of Git.

43
RULES/06-README.md Normal file
View File

@@ -0,0 +1,43 @@
## README
This is our rules for creating and managing a projects `README.md` file.
### Template
```
# Project Name
1–3 concise paragraphs explaining what the project does.
## Table of Contents
Clickable table of contents
## Requirements
- [Python](https://python.org)
- [request](https://pypi.org/project/requests)
- [Terraform](https://terraform.com)
###### System Recommendations
- 2GB Ram
- 50gb Disk
## Setup
pip install -r requirements or pip install [repo name]
or manual with git clone seup.sh etc.
or running setup.sh
talk about .env or settings to changeuse a table to give detail able them.
## Usage
how to run it the cli arguments in a table, etc
---
###### Mirrors: [SuperNETs](https://git.supernets.org/acidvegas/) • [GitHub](https://github.com/acidvegas/) • [GitLab](https://gitlab.com/acidvegas/) • [Codeberg](https://codeberg.org/acidvegas/)
```
- Clear, direct, human tone, not hyper-intelligent language that is obviously AI generated.
- Never use emojis or the `—` character in any comments, code, or README files.
- Vertically align markdown tables based on the largest item in each column with only 1 space after it.
- Text in parentheses should be italicized using `*()* ` format in markdown.
- If a project is controversial, for example, to spam/flood something, a malicious proof of concept, or some kind of recon/intel data scraping, then include a disclaimer saying you are not liable, made for testing with legal permission or on your own servers.

41
RULES/07-ENV.md Normal file
View File

@@ -0,0 +1,41 @@
## ENV
This is our rules for handling environment variables usage including requiring them, using them for sensitive settings, authentication, etc.
Create a `.env.example` file for any project that uses `.env` files. The example file will not be in `.gitignore`' and will serve as a template for whats expected in the`.env` file. Most people will do `cp .env.example .env` and then edit the `.env` to get started.
### Bash
Basic one-liner example to prefix a bash script to require and load a local `.env` file:
```bash
[ -f .env ] && source .env || { echo "error: missing .env file" && exit 1 }
```
Here is an example of doing an undefined environment variable fallback:
```bash
echo ${ADMIN_USERNAME:-admin}
```
### Python:
Here is an example of how most `config.py` files will look. This example makes the `.env` file itself optional as environment variables may be set externally, via `systemd`, `docker`, etc:
```python
import os
# Load .env if it exists
if os.path.exists('.env'):
try:
from dotenv import load_dotenv
except ImportError:
raise ImportError('missing python-dotenv library (pip install python-dotenv)')
else:
load_dotenv()
# Authentication settings
ADMIN_USERNAME = os.getenv('ADMIN_USERNAME', 'admin') # Has a default if undefined
ADMIN_PASSWORD = os.environ['API_KEY'] # Required
# Other settings
ENVIRONMENT = 'prod'
VERSION = '1.0.2b'
```

19
RULES/08-PYTHON-GENERAL.md Normal file
View File

@@ -0,0 +1,19 @@
## PYTHON - General Guidelines
- Always use Python virtual environments (venvs) for all projects to ensure dependency isolation.
- Prefer standard Python libraries before third-party PyPI libraries.
- Comments in code should be informative for simply explaining the flow of the code in English.
- Inline comments are only for small clarifications, avoid over-commenting
- Prefer an asynchronous design with `asyncio`.
- Avoid using the `requests` library if possible. More often than not we will opt for `aiohttp` but there is almost always a standard library way to do anything `requstes` can do, meaning we don't have to depend on PyPI packages if we don't need to.
- Use `_` inside of large int's, like `250_000` instead of `250000` for readability.
- Avoid doing any of the following:
- pointless variables declared
- gigantic functions with too many lines of code
- functions with too many arguments
- adding un-necessary or un-asked for delays with `sleep`
- using `subprocess` or `os` for something redundant, that can be done in Python *(like `curl` or `wget`)*.
- When killing a Python process that was started by the LLM, always verify afterwards that the process was actually terminated.
- For Flask applications, use separate files for web assets: `index.html`, `style.css`, and `utils.js` instead of inline code.

31
RULES/09-PYTHON-IMPORTS.md Normal file
View File

@@ -0,0 +1,31 @@
## PYTHON - Import Organization
Imports are done categorically, in order, with a blank line between each category:
1. **Standard Library - direct imports**
```python
import random
import sys
import time
```
2. **Standard Library - `from x import y`**
```python
from datetime import datetime
```
3. **Third-Party PyPI Libraries**
- All PyPI imports must match this format:
```python
try:
import requests
except ImportError:
raise ImportError('missing requests library (pip install requests)')
```
4. **Local Project Imports**
```python
from core import config, ftp, irc, utils
```
- Imports always belong at the top, never in the middle of code. The only exception is ones found after `if __name__ == '__main__:'.

25
RULES/10-PYTHON-FUNCTIONS.md Normal file
View File

@@ -0,0 +1,25 @@
## PYTHON - Function Conventions
- Use a naming convention format like `def event_message():` rather than `def eventMessage():` or other styling types.
- All functions should be in ABC order.
- Use type hints on arguments and return *(`def example(name: str) -> bool:`)*
- **Never** use `-> None:` as a return hint.
- Do not use `from typing import ...`, it makes type hints and return hints looks hideous.
- All functions should have a docstring matching the formats below for functions with and without arguments:
### Functions with Arguments
```python
def example_function(name: str, age: int) -> bool:
'''
This is a simple to the point minimal function with arguments description in 1 line.
:param name: The customers name
:param age: The customers age
'''
```
### Functions without Arguments
```python
def simple_function():
'''This is a simple to the point minimal function description in 1 line.```
```

14
RULES/11-PYTHON-STYLE.md Normal file
View File

@@ -0,0 +1,14 @@
## PYTHON - Code Style & Alignment
- Use single quotes only, double quotes inside nested f-strings.
- Vertically align assignments, dicts, parameters, comments, etc for readability, example:
```python
self.chunk_max = args.chunk_max * 1024 * 1024 # MB
self.chunk_size = args.chunk_size
self.es_index = args.index
```
- Inline comments should only have a single space before the `#`, not 2 spaces.
- Three blank lines before `if __name__ == '__main__'.
- Two blank lines after the last import.
- 1 blank line after a functions docstring line.
- 2 blank lines in between every function.

10
.cursor/rules/python-memory.mdc → RULES/12-PYTHON-MEMORY.md
View File

@@ -1,15 +1,9 @@
---
description: "Memory-safe data handling standards for Python applications"
alwaysApply: true
---
## Memory-Safe Data Handling
## PYTHON - Memory-Safe Data Handling
When reading large files or fetching large amounts of data *(files, URLs, streams)*, process incrementally to avoid high memory usage:
- `yield` or async generators
- Read line by line or in chunks
Storing a massive amount of data in variables can yield high memory usage which may be avoidable in certain situations.
Apply only when applicable *(don't overcomplicate small data handling)*.
Apply only when applicable *(don't overcomplicate small data handling)*.

35
RULES/13-PYTHON-LOGGING.md Normal file
View File

@@ -0,0 +1,35 @@
## PYTHON - Logging with APV
The [APV](https://pypi.org/project/apv/) library is preferred in all Python projects for logging. It wraps the standard logging library, allowing you to use `logging.info`, `logging.error`, `logging.debug`, `logging.warn`, `logging.fatal`, etc throughout the project without defining a `logger` variable.
### Setup Example
```python
import argparse
import apv
# Setup parser
parser = argparse.ArgumentParser()
parser.add_argument('-d', '--debug', action='store_true', help='Enable debug logging')
args = parser.parse_args()
# Setup logging via apv
if args.debug:
apv.setup_logging(level='DEBUG', log_to_disk=True, max_log_size=10*1024*1024, max_backups=5, log_file_name='application_log')
else:
apv.setup_logging(level='INFO')
```
### Usage Throughout Code
Once APV is initialized, use standard logging calls anywhere in your project:
```python
import logging
logging.info('Application started')
logging.debug('Debug information here')
logging.error('An error occurred')
logging.warn('Warning message')
logging.fatal('Critical error')
```

13
.cursor/rules/python-examples.mdc → RULES/14-PYTHON-PROJECT.md
View File

@@ -1,7 +1,4 @@
---
description: "Python project examples including main.py, setup.sh, and Dockerfile templates"
alwaysApply: true
---
## PYTHON - Project Code Examples
### Example main.py
@@ -53,10 +50,9 @@ if __name__ == '__main__':
asyncio.run(main())
```
- The [APV](https://github.com/acidvegas/apv) library was created by me & is preferred in all Python projects. It simply wraps the standard logging library, so throughout the whole project, you can simply use `logging.info`, `logging.error`, `logging.debug`, `logging.warn`,`logging.fatal`, etc, without needing to define a `logger` variable or do anything fancy.
---
### Example setup.sh:
### Example setup.sh
```bash
# Load environment variables
[ -f .env ] && source .env || { echo "Error: .env file not found"; exit 1; }
@@ -83,7 +79,6 @@ docker run -d --name container_name \
container_name
```
### Example Dockerfile
```Dockerfile
# Use the slim version of the Python image
@@ -98,7 +93,7 @@ WORKDIR /app
# Copy python requirements file
COPY requirements.txt .
# Set up Python environment & install dependencies
# Set up Python environment and install dependencies
RUN python3 -m pip install --upgrade pip && python3 -m pip install --no-cache-dir --only-binary :all: -r requirements.txt --upgrade
# Cleanup the python requirements file (not needed at runtime)

18
merge Executable file
View File

@@ -0,0 +1,18 @@
#!/usr/bin/env bash
# Merge all RULES markdown files into one
output_file="CLAUDE.md"
# Remove existing output file if it exists
rm -f "$output_file"
# Loop through all .md files in RULES directory in sorted order
for file in RULES/*.md; do
if [ -f "$file" ]; then
cat "$file" >> "$output_file"
echo -e "\n\n---\n" >> "$output_file"
fi
done
echo "Merged all rules into $output_file"