my-vault/AGENTS.md

Agent Coding Guidelines

Purpose: Code style and workflow for agentic coding assistants in this vault Last Updated: 2026-01-06

---

Build & Lint Commands

# Lint & format (auto-fixes issues)
pnpm lint                  # Run eslint + prettier with auto-fix

# Check only (no fixes)
pnpm lint:check            # Verify code style compliance

# Format only
pnpm format                # Prettier format all files
pnpm format:check          # Check formatting without changes

# Run scripts directly (no test framework configured)
node .scripts/update-attachment-links.js
GEMINI_API_KEY=xxx node .claude/mcp-servers/gemini-vision.mjs
python3 .scripts/rename-chinese-to-english.py

---

Code Style Guidelines

TypeScript/JavaScript

Imports

import type { Server } from '@modelcontextprotocol/sdk/server/index.js'
import { readFile } from 'node:fs/promises'
import path from 'node:path'
import fs from 'node:fs'

Formatting

// Single quotes for strings, use semicolons
const value = 'string'
const obj = { name, value }
const msg = `Hello ${name}`

Error Handling

// Always handle errors in async functions
try {
  await fs.access(filePath)
} catch {
  throw new Error(`File not found: ${filePath}`)
}

// Check environment variables early
if (!process.env.API_KEY) {
  console.error('❌ API_KEY environment variable is required')
  process.exit(1)
}

Naming Conventions

function analyzeImage(args) {} // camelCase
const MAX_ATTEMPTS = 60 // UPPER_SNAKE_CASE
const imagePath = 'path/to/file.png' // camelCase
class ImageAnalyzer {} // PascalCase
function process(data, _unused) {} // Prefix unused with _

Python Scripts

#!/usr/bin/env python3
# -*- coding: utf-8 -*-

from pathlib import Path
from typing import List, Dict

path = Path('05_Attachments/Organized')

def process_files(files: List[str]) -> Dict[str, str]:
    """Process list of files."""
    return {f: f for f in files}

file_path = 'path/to/file.md'  # snake_case
MAX_RETRIES = 3                # UPPER_SNAKE_CASE

---

File Organization

.claude/mcp-servers/    # MCP server implementations
.scripts/              # Utility scripts (JS/Python)
.config/               # Config files (eslint, prettier, tsconfig)

Script Structure

#!/usr/bin/env node

import fs from 'node:fs'

const args = process.argv.slice(2)
if (args.length !== 1) {
  console.log('Usage: node script.js <arg>')
  process.exit(1)
}

async function main() {
  // Implementation
}

main().catch(console.error)

---

Common Patterns

File Walking

function walkDir(dir, callback) {
  fs.readdirSync(dir).forEach((f) => {
    const dirPath = path.join(dir, f)
    const isDirectory = fs.statSync(dirPath).isDirectory()
    if (isDirectory && !f.includes('node_modules') && !f.includes('.git')) {
      walkDir(dirPath, callback)
    } else if (!isDirectory) {
      callback(dirPath)
    }
  })
}

Processing Files

walkDir('.', (filepath) => {
  if (filepath.endsWith('.md')) {
    let content = fs.readFileSync(filepath, 'utf8')
    // Process content
    if (content !== originalContent) {
      fs.writeFileSync(filepath, content, 'utf8')
    }
  }
})

---

Before Making Changes

1. Read existing files to understand patterns
2. Check package.json for available scripts/dependencies
3. Run lint before committing: pnpm lint
4. Test changes by running scripts directly
5. Commit with descriptive message after verification

---

Resources:

• ESLint: .config/eslint.config.js
• Prettier: .config/.prettierrc.js
• TypeScript: .config/tsconfig.json