Skip to content

AGENTS.md

Latest commit

 

History

History
98 lines (66 loc) · 3.44 KB

AGENTS.md

File metadata and controls

98 lines (66 loc) · 3.44 KB

AGENTS.md -- saar

Generated by saar. Re-run saar . --format agents to update auto-detected sections.

914 functions, 153 classes, 86 files.

Languages: python (79 files), typescript (5 files), javascript (2 files)

Frontend

Stack: React + TypeScript + Vite

  • Package manager: bun -- always use bun install, never npm/yarn
  • Styling: Tailwind CSS -- no raw CSS files

Coding Conventions

  • Functions: snake_case
  • Classes: PascalCase
  • Constants: UPPER_SNAKE_CASE
  • Files: snake_case

Key project imports:

from saar.models import CodebaseDNA
import numpy as np
import typer
from rich.console import Console
from saar.rl.agents.ucb_bandit import UCBContextualBandit
from saar.rl.agents.reinforce import REINFORCEAgent

Logging

  • Use logging.getLogger(__name__) -- never bare print()

Auth

  • Protected endpoints use Depends(reusable_oauth2) — never bypass with manual header parsing

Error Handling

  • Use domain exceptions: OCIAPIError, OCIAuthError
  • Log exceptions before re-raising

[43 lines omitted -- run saar extract --verbose for full output]

How to Verify Changes Work

Backend: pytest tests -v | Frontend: bun run build

Run these before considering any change done.

Tribal Knowledge

Captured via saar interview -- human knowledge static analysis cannot detect.

This project: CLI tool that extracts codebase DNA and generates AI context files (AGENTS.md, CLAUDE.md, .cursorrules) -- no server, no account, no API key required

Never Do

  • Always run tests inside venv: source venv/bin/activate && pytest tests/ -q -- system Python missing typer causes collection errors
  • 548 tests must pass before any commit
  • Never push directly to OpenCodeIntel/saar main. Never commit venv/ dist/ pycache
  • Never add external infrastructure dependencies (no Supabase, Redis, network calls in core path)
  • Never add command logic to cli.py -- it only registers app.command() calls. Logic goes in saar/commands/
  • Never add extraction logic to extractor.py -- DNAExtractor delegates to saar/extractors/ modules
  • benchmark/ contains OPE-99 results -- never delete benchmark_results.json or benchmark_report.md
  • saar has NO web auth -- any detected Depends(reusable_oauth2) is a false positive from test fixtures
  • Always run ruff check saar/ tests/ && pytest tests/ -q before committing
  • test rule for demo
  • test mistake
  • test rule audit
  • test capture audit
  • never import from saar.extractor directly
  • used npm instead of bun

Domain Vocabulary

  • DNA = extracted architectural patterns of a codebase (not genetic material)
  • Tribal knowledge = context only humans can provide: gotchas, domain terms, verification workflows -- static analysis cannot detect this
  • SAAR:AUTO-START/END markers = preservation markers separating auto-generated from human-written sections in generated files
  • budget = line cap on generated output (default 100 lines, --verbose for full)

Verification Workflow

source venv/bin/activate && pytest tests/ -q -- 548 tests must pass. Then: saar extract . --no-interview to verify CLI output is clean

Off-Limits Files

AI must never modify these:

  • saar/models.py -- core data contract, CodebaseDNA and all dataclasses, never modify without discussion

Additional Context

This repo dogfoods itself -- after any formatter change regenerate all context files: saar extract . --force --no-interview