Skip to content

AGENTS.md

Latest commit

 

History

History
69 lines (50 loc) · 4.58 KB

AGENTS.md

File metadata and controls

69 lines (50 loc) · 4.58 KB
Raw

AI Agent instructions for nighthawk-python

NON-NEGOTIABLE REQUIREMENTS

  • Do not edit files until all questions in the current chat session are resolved and explicit user permission is granted (except ExecPlans, Ideal State documents).
  • In chat sessions, communicate in Japanese; when writing to files, use English; internal reasoning may use any language.
  • When listing questions, confirmations, or proposed decisions, assign a short stable Id to each item so the user can respond inline.
    • Format: Q-SLUG-001 (questions), C-SLUG-001 (confirmations), P-SLUG-001 (proposals). Follow-ups: append suffix like Q-SLUG-001A.
    • Each item must be answerable on its own and must include its Id.
  • When the user requests "radical" changes, prioritize extensive, global, disruptive, and thorough edits over minimal fixes.

Naming and terminology

Allowed abbreviations (Glossary)

Id (Identifier), DSL (Domain Specific Language), LLM (Large Language Model), NH/nh (Nighthawk), max (maximum), min (minimum), loop indices i/j/k, type parameters P (ParamSpec), R (Return type), T (Type variable).

Rules

  • 改行 (line wrapping) は fixed column で hard-wrap しない.
    • User が column 上限を明示しない限り, 文末 / clause 区切り / list item など意味の区切りでのみ改行する (semantic line break).
  • Use full words in all identifiers unless listed above.
  • Disallowed abbreviations: ctx -> context, cfg -> configuration, repo -> repository, opts -> options, ref -> reference.
  • Map/Dict: (adjective + "_")* + key + "_to_" + value.
    • Do not pluralize value; collections use explicit suffix (_list, _set, _tuple).
    • Examples: binding_name_to_type, binding_name_to_field_name_to_value.
    • Counter-example: binding_types_dict_expression (dict-literal expression, not a lookup).
    • Fix violations opportunistically when touching the code.
  • Ask the user before doing broad renames across a file or the codebase.
  • ASCII punctuation only: ' (U+0027) and " (U+0022). No smart quotes.

Project orientation

A Python 3.13+ library embedding a "Natural" DSL inside Python functions, executed using an LLM. Provider dependencies are installed via extras. No CLI entry point.

Natural source, included Markdown, prompt fragments, and declarations are trusted program inputs authorized by the host under the trust contract; do not wire untrusted user input into Natural blocks or template preprocessing. For Nighthawk development, follow Programs used in development: generating or revising program assets during a tool's execution, then executing them, requires an explicitly authorized experiment; running an experiment does not authorize adopting its output.

ExecPlans: write under .agents/execplans/ only on request; follow .agents/PLANS.md.

Design references

  • Read Philosophy before architectural decisions and whenever a design or value judgment is unclear; check its invariants first.
  • Read Design drivers when using application requirements to justify Core changes or deciding which information belongs in this workspace.
  • Use Specification for supported behavior and Roadmap for exploratory directions; application scenarios do not establish runtime guarantees.
  • Treat Nighthawk-based development tooling as an application; its presence here does not make it a public library feature.

Development workflow

Python 3.13+, uv for dependencies, pytest for tests. Prefer LSP-based tooling for code analysis.

Command Purpose
uv run python Investigate interactively
uv sync --all-extras --all-groups Install/sync dependencies
uv run ruff format . Format
uv run ruff check --fix . Auto-fix lint
uv run pyright Type check
uv run pytest -q Tests (quiet)
NIGHTHAWK_OPENAI_INTEGRATION_TESTS=1 uv run pytest -q Integration tests (OpenAI)
NIGHTHAWK_CODEX_INTEGRATION_TESTS=1 uv run pytest -q Integration tests (Codex)
NIGHTHAWK_CLAUDE_SDK_INTEGRATION_TESTS=1 uv run pytest -q Integration tests (Claude Code SDK)
NIGHTHAWK_CLAUDE_CLI_INTEGRATION_TESTS=1 uv run pytest -q Integration tests (Claude Code CLI)

uv hardlinking warnings do not indicate failure. Suppress: export UV_LINK_MODE=copy.

Environment: OPENAI_API_KEY (OpenAI), CODEX_API_KEY (Codex).

Model evaluation commands, repeated trials, and evidence: see CONTRIBUTING.md "Model evaluations with pytest".