agents.md
This commit is contained in:
Julian Sutter
parent
26cf1cd241
commit
63b66fb98a
2 changed files with 469 additions and 0 deletions
310
.clinerules
Normal file
310
.clinerules
Normal file
|
|
@ -0,0 +1,310 @@
|
|||
# NixOS Configuration Repository - AI Agent Guidelines
|
||||
|
||||
This file contains project-specific rules and guidelines for AI agents working with this NixOS configuration repository. Follow these rules to ensure consistent, secure, and maintainable configurations.
|
||||
|
||||
## Core Principles
|
||||
|
||||
### 1. Declarative Configuration
|
||||
- All system state must be defined in Nix expressions
|
||||
- Never use imperative commands for permanent changes
|
||||
- Every configuration change should be reproducible
|
||||
|
||||
### 2. Modular Architecture
|
||||
- Maintain separation between hardware, software, and user configurations
|
||||
- Use existing modules before creating new ones
|
||||
- Follow the established directory structure strictly
|
||||
|
||||
### 3. Security First
|
||||
- Never expose sensitive data (passwords, private keys, API tokens)
|
||||
- Use proper user privilege separation
|
||||
- Validate all external inputs and configurations
|
||||
|
||||
## File Structure Rules
|
||||
|
||||
### Module Placement
|
||||
```
|
||||
desktop/ # Desktop environment configurations
|
||||
├── dev.nix # Development tools and languages
|
||||
├── gaming.nix # Games and gaming platforms
|
||||
├── media.nix # Audio/video software
|
||||
└── *.nix # Other desktop applications
|
||||
|
||||
systems/ # Hardware-specific configurations
|
||||
├── common.nix # Shared system settings
|
||||
├── framework.nix # Framework laptop
|
||||
└── hostname.nix # Other hardware configs
|
||||
|
||||
users/ # User configurations with Home Manager
|
||||
├── jsutter.nix # Primary user
|
||||
└── username.nix # Additional users
|
||||
|
||||
servers/ # Server-specific configurations
|
||||
├── common.nix # Base server settings
|
||||
└── service.nix # Specific services
|
||||
```
|
||||
|
||||
### File Naming Conventions
|
||||
- Use lowercase with hyphens: `vpn-config.nix`, `development-tools.nix`
|
||||
- System configurations must match hostname: `framework.nix`, `aurora.nix`
|
||||
- User configurations must match username: `jsutter.nix`, `isutter.nix`
|
||||
|
||||
## Nix/NixOS Specific Guidelines
|
||||
|
||||
### Function Parameters
|
||||
Always include these parameters in configuration modules:
|
||||
```nix
|
||||
{ config, pkgs, pkgs-unstable, lib, ... }: # For modules using unstable packages
|
||||
{ config, pkgs, lib, ... }: # For stable-only modules
|
||||
```
|
||||
|
||||
### Package Management Rules
|
||||
|
||||
#### Stable vs Unstable Packages
|
||||
```nix
|
||||
# PREFERRED: Use stable packages by default
|
||||
environment.systemPackages = with pkgs; [
|
||||
firefox
|
||||
git
|
||||
vim
|
||||
];
|
||||
|
||||
# ACCEPTABLE: Use unstable when necessary
|
||||
# Add comments explaining why unstable is needed
|
||||
environment.systemPackages = with pkgs; [
|
||||
firefox
|
||||
pkgs-unstable.windsurf # Latest features not in stable
|
||||
];
|
||||
```
|
||||
|
||||
#### Package Selection Criteria
|
||||
1. **Use stable unless**: Package doesn't exist OR needs newer version
|
||||
2. **Document reasons**: Always comment why unstable is used
|
||||
3. **Test thoroughly**: Unstable packages may have issues
|
||||
4. **Review regularly**: Check if unstable packages can move to stable
|
||||
|
||||
### Module Organization Patterns
|
||||
|
||||
#### System Configuration Pattern
|
||||
```nix
|
||||
{ config, lib, pkgs, ... }:
|
||||
{
|
||||
# Always include hostname first
|
||||
networking.hostName = "system-name";
|
||||
|
||||
# Hardware configuration
|
||||
fileSystems."/" = { ... };
|
||||
fileSystems."/boot" = { ... };
|
||||
|
||||
# System-specific settings
|
||||
# Group related configurations together
|
||||
}
|
||||
```
|
||||
|
||||
#### User Configuration Pattern
|
||||
```nix
|
||||
{ config, pkgs, pkgs-unstable, home-manager, ... }:
|
||||
{
|
||||
# System user definition
|
||||
users.users.username = {
|
||||
shell = pkgs.zsh;
|
||||
isNormalUser = true;
|
||||
description = "User Description";
|
||||
extraGroups = [ "networkmanager" "wheel" ]; # Only essential groups
|
||||
};
|
||||
|
||||
# Home Manager configuration
|
||||
home-manager.users.username = {
|
||||
home.username = "username";
|
||||
home.homeDirectory = "/home/username";
|
||||
home.stateVersion = "25.05";
|
||||
|
||||
# User configurations
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
## Security Rules
|
||||
|
||||
### Sensitive Data Handling
|
||||
- **NEVER** commit plaintext passwords
|
||||
- **NEVER** commit private SSH keys
|
||||
- **NEVER** commit API tokens or secrets
|
||||
- **ALWAYS** use hashed passwords: `hashedPassword = "$6$..."`
|
||||
- **CONSIDER** using sops-nix for advanced secret management
|
||||
|
||||
### User Privilege Management
|
||||
```nix
|
||||
# GOOD: Minimal necessary groups
|
||||
extraGroups = [ "networkmanager" "wheel" "audio" ];
|
||||
|
||||
# BAD: Over-privileged users
|
||||
extraGroups = [ "networkmanager" "wheel" "audio" "video" "input" "disk" "lp" "scanner" ];
|
||||
```
|
||||
|
||||
### SSH Key Management
|
||||
```nix
|
||||
# GOOD: Use authorizedKeys for SSH access
|
||||
openssh.authorizedKeys.keys = [
|
||||
"ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIBNVUh+RrcOSMRV6qysnsdPs5AyK8dSm4QhhnwgpikyI user@domain"
|
||||
];
|
||||
|
||||
# FORBIDDEN: Never include private keys
|
||||
```
|
||||
|
||||
## Configuration Best Practices
|
||||
|
||||
### Code Style
|
||||
- Use 2-space indentation
|
||||
- Align attribute lists consistently
|
||||
- Add comments for non-obvious configurations
|
||||
- Group related configurations together
|
||||
|
||||
### Module Dependencies
|
||||
- Avoid circular dependencies between modules
|
||||
- Use proper imports for shared utilities
|
||||
- Document module dependencies in comments
|
||||
|
||||
### Resource Management
|
||||
```nix
|
||||
# GOOD: Enable services only when needed
|
||||
services.openssh.enable = true;
|
||||
services.printing.enable = false;
|
||||
|
||||
# GOOD: Configure sensible defaults
|
||||
boot.kernelPackages = pkgs.linuxPackages_latest;
|
||||
|
||||
# GOOD: Enable garbage collection
|
||||
nix.gc = {
|
||||
automatic = true;
|
||||
dates = "weekly";
|
||||
options = "--delete-older-than 7d";
|
||||
};
|
||||
```
|
||||
|
||||
## Testing and Validation
|
||||
|
||||
### Pre-commit Testing
|
||||
ALWAYS run these commands before submitting changes:
|
||||
|
||||
```bash
|
||||
# 1. Syntax check
|
||||
nix flake check
|
||||
|
||||
# 2. Dry run for affected systems
|
||||
sudo nixos-rebuild dry-run --flake .#framework
|
||||
sudo nixos-rebuild dry-run --flake .#aurora
|
||||
sudo nixos-rebuild dry-run --flake .#labrizor
|
||||
|
||||
# 3. Check flake outputs
|
||||
nix flake show
|
||||
```
|
||||
|
||||
### Build Verification
|
||||
- Test on at least one system before merging
|
||||
- Verify all services start correctly
|
||||
- Check for package conflicts
|
||||
- Validate hardware-specific configurations
|
||||
|
||||
### Rollback Planning
|
||||
- Always know how to rollback changes
|
||||
- Keep previous generation available
|
||||
- Document critical system dependencies
|
||||
|
||||
## Common Workflows
|
||||
|
||||
### Adding New Packages
|
||||
1. **Determine appropriate module** (desktop/, systems/, users/)
|
||||
2. **Check if package exists** in stable channel
|
||||
3. **Use unstable only if necessary** with documentation
|
||||
4. **Test with dry-run** before applying
|
||||
5. **Update relevant documentation**
|
||||
|
||||
### Creating New Modules
|
||||
1. **Follow existing patterns** in similar modules
|
||||
2. **Include proper function parameters**
|
||||
3. **Add descriptive comments**
|
||||
4. **Test module independently**
|
||||
5. **Update flake.nix** if needed
|
||||
|
||||
### System Modifications
|
||||
1. **Identify correct system file** in `systems/`
|
||||
2. **Backup current configuration**
|
||||
3. **Make minimal, focused changes**
|
||||
4. **Test thoroughly on target system**
|
||||
5. **Document hardware-specific requirements**
|
||||
|
||||
## Forbidden Patterns
|
||||
|
||||
### NEVER DO THESE:
|
||||
- **Hardcode paths**: Use Nix store paths or derivations
|
||||
- **Ignore errors**: All configuration errors must be resolved
|
||||
- **Skip testing**: Always validate changes before applying
|
||||
- **Mix concerns**: Don't put desktop configs in system files
|
||||
- **Use mutable state**: Avoid commands that modify /etc directly
|
||||
|
||||
### INSTEAD DO THESE:
|
||||
- **Use proper Nix expressions** for all configurations
|
||||
- **Handle errors explicitly** with appropriate error messages
|
||||
- **Test before deploying** with dry-run and build tests
|
||||
- **Maintain separation** between hardware, software, users
|
||||
- **Use declarative approach** for all system changes
|
||||
|
||||
## Documentation Requirements
|
||||
|
||||
### Code Comments
|
||||
- Explain non-obvious configurations
|
||||
- Document reasons for unstable package usage
|
||||
- Note hardware-specific requirements
|
||||
- Reference external dependencies
|
||||
|
||||
### Commit Messages
|
||||
- Use clear, descriptive commit messages
|
||||
- Reference affected systems/modules
|
||||
- Explain reasoning for significant changes
|
||||
- Include testing steps when applicable
|
||||
|
||||
## Emergency Procedures
|
||||
|
||||
### System Recovery
|
||||
If a system fails to boot after changes:
|
||||
1. Boot from installation media
|
||||
2. Mount root filesystem: `mount /dev/disk/by-partlabel/primary /mnt`
|
||||
3. Roll back: `sudo nixos-rebuild switch --rollback`
|
||||
4. Identify and fix configuration issues
|
||||
5. Test before rebooting
|
||||
|
||||
### Configuration Rollback
|
||||
```bash
|
||||
# List available generations
|
||||
sudo nix-env --list-generations --profile /nix/var/nix/profiles/system
|
||||
|
||||
# Rollback to previous working generation
|
||||
sudo nixos-rebuild switch --profile-name generation-123
|
||||
|
||||
# Or use rollback shortcut
|
||||
sudo nixos-rebuild switch --rollback
|
||||
```
|
||||
|
||||
## Agent-Specific Rules
|
||||
|
||||
### Before Making Changes
|
||||
1. **Read existing documentation** in docs/
|
||||
2. **Understand current configuration** patterns
|
||||
3. **Identify impact scope** of proposed changes
|
||||
4. **Plan testing strategy** for affected systems
|
||||
|
||||
### During Development
|
||||
1. **Follow established patterns** exactly
|
||||
2. **Add appropriate comments** explaining changes
|
||||
3. **Test incrementally** with dry-run checks
|
||||
4. **Document new patterns** if introducing changes
|
||||
|
||||
### After Changes
|
||||
1. **Run complete test suite**
|
||||
2. **Update relevant documentation**
|
||||
3. **Verify all systems** build successfully
|
||||
4. **Commit with clear message** describing changes
|
||||
|
||||
---
|
||||
|
||||
These rules ensure consistent, secure, and maintainable NixOS configurations. Follow them strictly, and ask for clarification when unsure about any requirement.
|
||||
Loading…
Add table
Add a link
Reference in a new issue