From 21042ec1338e2e27df582477251d6e13897db6b9 Mon Sep 17 00:00:00 2001 From: Johan Lundberg Date: Thu, 22 Jan 2026 10:25:07 +0100 Subject: [PATCH] added AGENTS.md --- AGENTS.md | 187 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 187 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..51a7a94 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,187 @@ +# AGENTS.md + +This file provides guidance for AI coding agents working in this repository. + +## Project Overview + +Top 500 Albums analysis with data from Rolling Stone (2020) and Wikipedia (2023). Includes Python data processing scripts, an interactive web interface (vanilla HTML/CSS/JS), and album cover artwork from the iTunes API. + +## Build/Lint/Test Commands + +**No formal build system.** All Python scripts use only the standard library. + +```bash +# Run Python scripts directly +python scripts/download_all_covers.py +python scripts/compare_top500_albums.py + +# Local dev server (required for CORS) +python -m http.server 8000 +``` + +**No tests or linting configured.** Manual testing only - run scripts and verify output, open website and check functionality. + +## Code Style Guidelines + +### Python + +```python +#!/usr/bin/env python3 +"""Module docstring explaining the script's purpose.""" + +import csv +import json +import os +import re +from typing import Dict, List, Optional, Tuple + +# Constants: UPPER_SNAKE_CASE +MAX_RETRIES = 3 + +# Functions/variables: snake_case +def normalize_text(text: str) -> str: + """Normalize text for comparison.""" + pass + +albums_2020 = {} +``` + +**Key patterns:** +- Always use shebang: `#!/usr/bin/env python3` +- Include module-level docstring +- Standard library only - no external dependencies +- Type hints for function signatures +- Use `encoding='utf-8'` and `newline=''` for CSV operations + +**Error handling:** +```python +try: + with urllib.request.urlopen(url, timeout=15) as response: + data = json.loads(response.read().decode()) +except Exception as e: + print(f"Error: {e}") + return None +``` + +### JavaScript + +```javascript +// Global variables at top +let albumsData = []; +const itemsPerPage = 50; + +// DOM refs cached on load +const albumsGrid = document.getElementById('albumsGrid'); + +// Initialize on DOMContentLoaded +document.addEventListener('DOMContentLoaded', function() { + loadData(); +}); + +// Async/await for fetch +async function loadAlbumsData() { + try { + const response = await fetch('data.csv'); + if (!response.ok) throw new Error('Failed'); + // ... + } catch (err) { + console.error('Error:', err); + } +} +``` + +**Key patterns:** +- Variables/functions: camelCase +- Use `console.warn()` for non-critical failures +- Vanilla JS only - no frameworks + +### HTML/CSS + +- Semantic HTML5 elements +- CSS custom properties for theming +- Responsive design with Grid/Flexbox + +## Accessibility Requirements + +All UI changes must follow WCAG 2.1 AA guidelines: + +**Keyboard Navigation:** +- All interactive elements must be keyboard accessible +- Use `tabindex` appropriately (0 for focusable, -1 for programmatic focus) +- Implement visible focus indicators (`:focus-visible` with `outline`) +- Support skip links for main content + +**Screen Readers:** +- Use semantic HTML (`