Skip to content

add initial AGENTS.md#848

Open
sgfost wants to merge 5 commits intocomses:mainfrom
sgfost:agents-md
Open

add initial AGENTS.md#848
sgfost wants to merge 5 commits intocomses:mainfrom
sgfost:agents-md

Conversation

@sgfost
Copy link
Contributor

@sgfost sgfost commented Feb 6, 2026

The purpose of this is to condense important information about the codebase into one relatively short file for coding agents (cursor/claude/etc.) to have at the top of their context. It should get added to/change over time

The rule that I'm going by is: whenever you find yourself reminding an agent about how something works, or how to do something, add it to AGENTS.md

resolves comses/planning#347

@sgfost sgfost requested a review from asuworks February 6, 2026 01:03
Copy link
Contributor

@asuworks asuworks left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How about this:
#857

asuworks and others added 3 commits March 3, 2026 12:55
17 .mdc rule files covering all major subsystems: overview, Django backend,
DRF API layer, permissions, Vue frontend, hybrid rendering, Wagtail CMS,
peer review workflow, BagIt archival, DataCite DOI, Discourse SSO, tag
curation, spam moderation, invoke tasks, conferences, testing, and ES search.

Includes analysis of airweave cursor rules as reference pattern and a
generation prompt documenting the methodology.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…ions)

Convert .cursor/rules/*.mdc to tool-agnostic instruction files:
- AGENTS.md hierarchy (root + django/ + library/ + frontend/ + home/)
  with progressive disclosure (327 lines, 7.4:1 compression from 2,434)
- CLAUDE.md and GEMINI.md symlinks to AGENTS.md
- .github/copilot-instructions.md (root copy)
- .github/instructions/*.instructions.md (1:1 from .mdc, full content)

Original .cursor/rules/*.mdc files are unchanged.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Add project identity, stack summary, current state, and 6 new conventions
(fat models, Composition API, vorms, migrations, data-cy selectors, shared
volume). Add dev commands (shells, manage.py, vite tls, localhost URL).
Frontend: vorms, date parsing, Prettier fix, composables directory.
Django: PEP 8, type hints, Huey task discovery, migration convention.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@asuworks
Copy link
Contributor

asuworks commented Mar 3, 2026

Considering https://umesh-malik.com/blog/agents-md-ai-coding-agents-study

Idea for this PR is:

  1. Create small structured AGENTS.md files throughout major parts of the repo which broadly hint at important things.
  2. .cursor/rules/*.mdc and .github/instructions/*.instructions.md are the same files for cursor and copilot respectively. They might be not necessary at all because we should let the agents do their agentic exploration for the task at hand.
  3. AGENTS.md should be evergreen content updated whenever an agent fails to do some task. When the agent finally succeeds (with human guiding), ask the agent: "What instruction made you struggle during this session? How would you change it? Update the corresponding AGENTS.md".

Inspiration for cursor rules: https://github.com/airweave-ai/airweave/tree/main/.cursor/rules
Copilot best practices: https://docs.github.com/en/enterprise-cloud@latest/copilot/tutorials/coding-agent/get-the-best-results

@asuworks
Copy link
Contributor

asuworks commented Mar 3, 2026

Integrated with this PR so as not to lose @sgfost's initial work + evolution. Pushed 3 additional commits that expand the original AGENTS.md into:

  • AGENTS.md hierarchy (root + django/ + django/library/ + django/home/ + frontend/) — progressive disclosure as agents navigate deeper
  • .cursor/rules/*.mdc — 17 subsystem-specific rule files
  • .github/copilot-instructions.md + .github/instructions/*.instructions.md — GitHub Copilot equivalents
  • CLAUDE.md and GEMINI.md symlinksAGENTS.md

These are local working notes, not intended for the repository.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants