Skip to content

Doc/update agentsmd #101

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
harumiWeb merged 2 commits into from
Mar 15, 2026
Merged

Doc/update agentsmd #101

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b5e9049
update
Mar 15, 2026
bd53ef2
update
Mar 15, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
90 changes: 27 additions & 63 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,27 @@
# ExStruct AI Agents Guide

## 0. Overview

This repository is organized around the following top-level directories:

```text
exstruct/
|- src/ # Main library and implementation code
|- tests/ # Automated tests
|- sample/ # Sample workbooks and example inputs
|- schemas/ # JSON schemas and validation-related assets
|- scripts/ # Utility and maintenance scripts
|- benchmark/ # Benchmark code and performance measurements
|- docs/ # User-facing documentation
|- dev-docs/ # All developer-facing documentation
|- tasks/ # Temporary task notes and working files
|- drafts/ # Draft documents and work-in-progress materials
|- dist/ # Build artifacts and packaged outputs
`- site/ # Generated documentation site output
```

For internal development guidance, architecture notes, ADRs, specifications, and testing references, use `dev-docs/` as the canonical location. Developer-facing documentation should be written there rather than scattered across the repository.

## 1. Workflow Design

### 1. Use Plan mode by default
Expand Down Expand Up @@ -49,65 +71,7 @@

---

## 2. Coding Standards the AI Must Follow

The AI must always generate code according to the following rules.

### 2.1 Type Hints Required (mypy strict compliant)

- Always add argument and return types to every function and method
- `Any` may be used only at external library boundaries (xlwings, pandas, etc.)

### 2.2 Return Pydantic BaseModel or dataclass

- Do not return dictionaries or tuples
- Represent all structured data using Pydantic or dataclass models

### 2.3 One function = one responsibility

- Complexity (C90) must not exceed 12
- If needed, the AI may automatically split functions

### 2.4 Import order

1. Standard library
2. Third-party
3. Modules within exstruct

### 2.5 Docstrings (Google style)

All functions and classes must have Docstrings.

### 2.6 Do not depend on the internal structure of external libraries

- Do not infer types from xlwings / pandas / numpy and similar libraries
- Receive entities as Any at the boundary layer and normalize them internally with Pydantic

---

## 3. Code the AI Must Not Write (Prohibited Patterns)

The AI must not write the following code.

### ❌ Large single function (God Function)

### ❌ God class (God Object)

### ❌ Unnecessary nesting and deeply nested conditionals

### ❌ Returning dictionaries or tuples (Pydantic or dataclass required)

### ❌ Code that depends on internal types in xlwings or pandas

### ❌ Code with disorganized imports

### ❌ Functions full of side effects that cannot be tested

If necessary, the AI may **refactor to avoid these prohibited patterns**.

---

## 4. Areas Outside the AI's Responsibility (Handled by Humans)
## 2. Areas Outside the AI's Responsibility (Handled by Humans)
Copy link

@chatgpt-codex-connector chatgpt-codex-connector bot Mar 15, 2026

Choose a reason for hiding this comment

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

P2 Badge Restore coding standards section referenced by workflow

This edit removes the entire coding-standards/prohibited-pattern guidance block, but the Required Work Procedure still tells agents to implement code while “following the standards above,” so the document now contains a dangling requirement with no concrete standards to follow. In practice this makes agent behavior less deterministic and weakens reviewability of generated changes; either keep a standards section here or update the workflow step to point to another explicit source of coding rules.

Useful? React with 👍 / 👎.


The AI does not own the following areas. Humans make these decisions.

Expand All @@ -120,7 +84,7 @@ However, the AI **may make proposals**.

---

## 5. Required Work Procedure
## 3. Required Work Procedure

The AI must always follow the steps below before generating code.

Expand All @@ -137,7 +101,7 @@ The AI must always follow the steps below before generating code.

---

## Task Management
## 4. Task Management

1. **Plan first**: Write the plan in `tasks/todo.md` as checkable items
2. **Review the plan**: Review it before starting implementation
Expand All @@ -148,7 +112,7 @@ The AI must always follow the steps below before generating code.

---

## Documentation Retention Policy
## 5. Documentation Retention Policy

### Separation of Roles

Expand Down Expand Up @@ -211,7 +175,7 @@ The AI must always follow the steps below before generating code.

---

## Core Principles
## 6. Core Principles

- **Simplicity first**: Keep every change as simple as possible. Minimize the code affected.
- **No cutting corners**: Find the root cause. Avoid temporary fixes. Maintain senior engineer standards.
Expand Down
Loading