From b5e9049d2fec26ba9fa8235af6d04c1c7bfe3a7f Mon Sep 17 00:00:00 2001 From: harumiWeb Date: Sun, 15 Mar 2026 17:45:37 +0900 Subject: [PATCH 1/2] update --- AGENTS.md | 70 ++++++------------------------------------------------- 1 file changed, 7 insertions(+), 63 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 31f0b43..e5fb093 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,5 +1,7 @@ # ExStruct AI Agents Guide +## 0. Overview + ## 1. Workflow Design ### 1. Use Plan mode by default @@ -49,65 +51,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) The AI does not own the following areas. Humans make these decisions. @@ -120,7 +64,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. @@ -137,7 +81,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 @@ -148,7 +92,7 @@ The AI must always follow the steps below before generating code. --- -## Documentation Retention Policy +## 5. Documentation Retention Policy ### Separation of Roles @@ -211,7 +155,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. From bd53ef223fb63bb803a9bd1fd55677007c5d210e Mon Sep 17 00:00:00 2001 From: harumiWeb Date: Sun, 15 Mar 2026 17:52:50 +0900 Subject: [PATCH 2/2] update --- AGENTS.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index e5fb093..109690a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,6 +2,26 @@ ## 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