darc39/project-lore

Project Lore

Create or refresh .ai/project-lore.md: a short, evidence-based project memory that helps future AI agents avoid rediscovering commands, architecture, conventions, setup requirements, and gotchas.

Every line in the output must pass this test:

Would removing this line cause an AI agent to make a mistake?

Exclude generic advice, file-by-file directory listings, standard language conventions, and claims not supported by repository evidence.

Output Contract

Write only .ai/project-lore.md. Do not create or modify CLAUDE.md, AGENTS.md, .cursor/rules/, Copilot instructions, or other tool-specific files.

The lore file must be plain Markdown with no frontmatter or tool-specific directives. Write for "an AI agent working in this repository", not for a specific product.

Prefer concise bullets with exact commands and file references:

- Run one Go package test with `go test ./internal/foo -run TestName -count=1`.
- HTTP handlers live in `internal/handler`; business logic belongs in `internal/service`.
- Do not edit `api/generated/`; regenerate it with `make generate`.

Workflow

Follow these phases in order. Keep discovery bounded and evidence-driven.

Phase 1: Discover Project Signals

Read relevant files if they exist. Use rg --files or equivalent bounded listing first; avoid recursive dumps of large trees.

Prioritize:

• Project manifests: package.json, Cargo.toml, pyproject.toml, go.mod, pom.xml, build.gradle, Makefile, justfile, Taskfile.yml
• README and setup docs: README*, docs/, CONTRIBUTING*
• CI: .github/workflows/, .gitlab-ci.yml, Jenkinsfile, buildkite/circle config
• AI/context files: CLAUDE.md, AGENTS.md, .cursor/rules/, .cursorrules, .github/copilot-instructions.md, .windsurfrules, .clinerules
• Existing lore: .ai/project-lore.md
• Tooling config: linter, formatter, test, codegen, migration, and environment config files

For project-local skills under .codex/skills/ or .claude/skills/, read only their SKILL.md frontmatter or short index first. Open full skill bodies only when they encode workflows directly relevant to this repository.

Also run:

git log --oneline -20

Use it for recent development focus and commit-message conventions. Do not infer branch naming unless branch names appear in repository docs or messages.

Record:

• Language(s), framework(s), package manager(s)
• Monorepo, single project, or multi-module shape
• Build, test, lint, format, codegen, migration, and dev-server commands
• Required local services, external tools, env vars, or secrets
• Generated, vendored, or build-output paths that should not be hand-edited

Phase 2: Read the Code Skeleton

Read enough source to understand how the project actually works. Do not read every file.

Map the structure:

• Entry points (cmd/*/main.go, src/index.ts, app/main.py, etc.)
• Routing, command registration, or job wiring
• Core layers or module boundaries
• Shared utilities, types, config, logging, middleware, database, migrations, and codegen
• Test locations and test helpers

Then read key files in full:

• Main entry point(s)
• Router/controller/CLI registration
• Config loading
• Database or persistence setup
• Middleware/plugin/extension registration
• Key interfaces, base classes, protocols, schemas, or generated-code boundaries

Write down the actual flow in your own words before generating lore: request/command/job enters here, passes through these layers, and exits here.

Phase 3: Sample Conventions

Spot-check 5-10 representative source files across important modules. Look for conventions that differ from language or framework defaults:

• Import grouping or dependency direction
• Naming patterns
• Error handling
• Logging
• Async/concurrency patterns
• Test style and fixtures
• Comment/docstring expectations
• Legacy directories or exceptions to normal rules

Only document conventions that would change how an agent edits code.

Phase 4: Find Sharp Edges

Actively look for mistakes a new agent would make:

• Generated files that require codegen instead of manual edits
• Hidden setup steps, local services, env vars, or required tools
• Tests that require ordering, isolation, ports, Docker, or databases
• Mixed old/new APIs or incomplete migrations
• Platform-specific paths or commands
• Hardcoded values that look configurable but are not
• Architectural dependency rules not enforced by the language

Phase 5: Write or Refresh Lore

If .ai/project-lore.md does not exist, create .ai/ and write the file.

Start with:

# Project Lore

This file captures repository-specific context for an AI agent working in this project:
commands, architecture, conventions, setup requirements, and gotchas that are not obvious
from a quick file listing.

> Every line should pass this test: would removing it cause an AI agent to make a mistake?

Suggested sections, only when evidence supports them:

## Commands
## Architecture
## Conventions
## Setup & Environment
## Generated / Do Not Edit
## Testing Notes
## Gotchas
## Repo Etiquette

Use exact commands, paths, and concise rationale. Omit empty sections.

If .ai/project-lore.md already exists:

1. Read it fully.
2. Preserve useful existing lore unless evidence shows it is stale or generic.
3. Apply surgical edits: add missing facts, update stale commands, remove unsupported or low-value lines.
4. If the user asked only for review, preview, or critique, propose the patch instead of writing.
5. Otherwise update the file directly and summarize what changed.

Phase 6: Verify

Before finishing, verify the lore file:

• Every command is copied from project evidence or clearly derived from existing scripts/config.
• Every architectural claim has at least one supporting file path.
• No bullet merely repeats a directory tree.
• No generic advice applies equally to any project.
• No tool-specific output syntax, product names, or frontmatter appears in .ai/project-lore.md.
• Existing useful lore was preserved during refresh.

Run a lightweight readback of .ai/project-lore.md after writing and remove anything that fails the line-removal test.

Phase 7: Summarize

Tell the user:

• Where the lore file was created or updated
• Which high-signal sections changed
• Any notable unknowns or verification gaps
• When to refresh it, such as after major command, architecture, setup, or workflow changes

Do Not

• Do not run install commands such as npm install, pip install, bundle install, or commands that modify the environment.
• Do not make network calls unless the repository's own instructions require external documentation and the user asked for that depth.
• Do not invent commands or conventions.
• Do not list every file or directory.
• Do not overwrite existing lore wholesale when a surgical update is possible.
• Do not edit this skill file during normal project-lore runs. If the skill itself seems deficient, mention the improvement in the final summary and wait for an explicit request to update the skill.