Commit 3e864bc3 authored by Jan Reimes's avatar Jan Reimes
Browse files

docs(agents): restructure AGENTS.md for clarity and organization 

- Added project structure section with parsing command.
- Updated commands section with detailed task descriptions.
- Introduced heuristics for quick decision-making.
- Clarified boundaries and documentation guidelines.
parent da659a68

AGENTS.md

+99 −24
Original line number Diff line number Diff line
@@ -2,41 +2,116 @@ 


CLI tool for querying structured 3GPP document data.



## Commands

**Precedence:** The **closest `AGENTS.md`** to files you're changing wins. Root holds global defaults only.



## Project Structure



```bash

uv run pytest -v           # Run tests

ruff check src/ tests/     # Lint

uv add <package>           # Add dependency

The project structure can be parsed using the following command from the root of the repository:



```shell

rg --files | tree-cli --fromfile

```



## Critical Constraints

Notes:



- **NEVER** suppress linter issues with `# noqa` in `src/` or `tests/`

- **MUST NOT introduce:** `PLC0415`, `ANN001`, `E402`, `ANN201`, `ANN202`

- Use `uv run` for all Python commands

- `.env` files **MUST NOT** be committed

- **Never** run `git commit` or `git push` autonomously

- Command requires `ripgrep` and `tree-cli` tools, which can be installed in the project via: `mise up`.

- Files/folders are never listed in the present file, always generate the structure on the fly using the above command!



## Commands



| Task | Command | ~Time |

|------|---------|-------|

| Lint | `ruff check src/ tests/` | ~5s |

| Test (all) | `uv run pytest -v` | ~2m |

| Test (single) | `uv run pytest tests/test_file.py -v` | ~5s |

| Coverage | `uv run pytest --cov=src --cov-report=term-missing` | ~2m |

| Add dependency | `uv add <package>` | ~10s |



> If commands fail, verify against pyproject.toml or ask user to update.



## File Map



| Directory | Purpose |

|-----------|---------|

| `src/tdoc_crawler/` | Core crawler library (see scoped AGENTS.md) |

| `src/tdoc_crawler/cli/` | CLI commands (typer/rich) |

| `src/tdoc_crawler/tdocs/` | TDoc crawling and sources |

| `src/tdoc_crawler/specs/` | Specification operations |

| `src/tdoc_crawler/meetings/` | Meeting data handling |

| `src/tdoc_crawler/parsers/` | Parsing logic (Excel, HTML, etc.) |

| `packages/tdoc-ai/` | AI embeddings, graphs, search |

| `packages/convert-lo/` | LibreOffice document conversion |

| `packages/pool-executors/` | Serial/parallel executor utilities |

| `tests/` | Test suite (see tests/AGENTS.md) |



## Golden Samples (follow these patterns)



| For | Reference | Key patterns |

|-----|-----------|--------------|

| CLI command | `src/tdoc_crawler/cli/tdoc_app.py` | Typer app, Rich console |

| Pydantic model | `src/tdoc_crawler/models/` | Data validation, serialization |

| HTTP caching | `src/tdoc_crawler/http_client.py` | `create_cached_session()` |

| Test structure | `tests/test_crawler.py` | Fixtures, mocking, isolation |



## Heuristics (quick decisions)



| When | Do |

|------|-----|

| Adding HTTP request | Use `create_cached_session()` |

| Unsure import path | Check scoped AGENTS.md for domain |

| Circular import detected | Extract shared types to `models/` |

| Adding dependency | Ask first - minimize deps |

| 3GPP domain question | Load `3gpp-*` skills |



## Code Style

## Boundaries



### Always Do



- Use `uv run` for all Python commands

- Use `logging` over `print()`

- Explain **WHY**, not WHAT in comments

- Type hints mandatory (`T | None` not `Optional[T]`)

- Use `is`/`is not` for `None` comparisons

- `logging` over `print()`

- Explain **WHY**, not WHAT

- Run lint before claiming work complete



## Documentation

### Ask First



- **Skills:** `docs/skills-reference.md`

- **Testing:** `tests/AGENTS.md`

- **Packages:** See respective `AGENTS.md` files

- Adding new dependencies

- Modifying public API signatures

- Running full test suite (>2m)

- Repo-wide refactoring



### Never Do



- Suppress linter issues with `# noqa` in `src/` or `tests/`

- Introduce: `PLC0415`, `ANN001`, `E402`, `ANN201`, `ANN202`

- Commit `.env` files

- Run `git commit` or `git push` autonomously

- Duplicate code (search first, refactor if needed)



## Terminology



## Packages

| Term | Means |

|------|-------|

| TDoc | 3GPP Temporary Document (e.g., `S4-250638`) |

| Spec | 3GPP Technical Specification (TS/TR, e.g., `TS 26.444`) |

| WG | Working Group (e.g., S4, RAN1, CT3) |

| TSG | Technical Specification Group (SA, RAN, CT) |

| Portal | 3GPP EOL authenticated portal |



| Location | Purpose |

|----------|---------|

| `src/tdoc_crawler/` | Core crawler library |

## Scoped AGENTS.md (MUST read when working in these directories)



| Directory | Purpose |

|-----------|---------|

| `src/tdoc_crawler/` | Import patterns, HTTP caching, anti-duplication |

| `src/tdoc_crawler/cli/` | CLI patterns |

| `packages/tdoc-ai/` | AI document processing |

| `packages/teddi-mcp/` | ~~TEDDI MCP server~~ (moved to separate repo) |

| `packages/tdoc-ai/` | AI pipeline, embeddings, graph patterns |

| `packages/convert-lo/` | LibreOffice conversion |

| `tests/` | Testing patterns, fixtures, coverage |



> **Agents:** When editing files in listed directories, load its AGENTS.md first. It contains directory-specific conventions that override this root file.



## Documentation



- **Skills:** `docs/skills-reference.md`

- **3GPP Skills:** Load `3gpp-basics`, `3gpp-tdocs`, etc. for domain context