ユーザー: この文章を読み特にADRの取り扱いについてのAGENTS.mdを作成したい。複数ドキュメントに分けてリンクをはるかたちで最後は圧縮する。docs/standards/xxx.doc に標準的な挙動を出力して常に守るようにしたい。
AIの思考プロセス
Analyzing Harness Engineering
I've been immersed in analyzing the "Claude Code / Codex ユーザーのための誰でもわかるHarness Engineeringベストプラクティス" blog post from 2026. My focus is on extracting key Harness Engineering best practices for potential inclusion in AGENTS.md. I'm starting to identify recurring themes and actionable insights that are useful to expert users.
Defining ADR Strategy
I'm now defining the strategy for Architecture Decision Records (ADRs) within AGENTS.md. I intend to create several linked documents, focusing specifically on ADR handling. The goal is a concise AGENTS.md (under 50 lines), acting as a pointer to detailed documentation in docs/standards/, such as docs/standards/adr.md. This will establish standard behaviors for agents, ensuring ADRs are treated as the single source of truth within the repository.
Refining ADR Workflow
I'm now refining the ADR workflow, focusing on linkage and directory structure. I'm keen on the "Archgate pattern," linking error messages and prompts directly to ADRs to preserve decision history and manage states with "Superseded/Deprecated." I'm planning out the file structure, specifically focusing on how to organize AGENTS.md, docs/standards/, and docs/adr/.
Defining ADR Behaviors
I am now focusing on defining the standard behaviors for ADRs, like reading, writing, and managing them. I'm prioritizing non-destructive updates: new ADRs for changes, marking old ones as "Superseded" or "Deprecated." I am planning how to integrate ADRs with custom linters and architectural rules to make decisions actionable. Next, I'm working on the ideal format standards for ADRs.
Drafting Agent Guidelines
I'm currently drafting AGENTS.md and outlining strict guidelines for agent behavior. The focus is on a streamlined, concise file that directs users to the full ADR workflow documentation. It's crucial agents understand the ADR system, adhere to linting, avoid destructive actions, and leverage the "Archgate pattern" for architectural constraints. My latest draft includes a clear structure for routing, prohibitions, and core commands.
Finalizing ADR Standards
I'm finalizing the ADR standards documentation in docs/standards/adr-workflow.md, incorporating the principles of immutability and the Archgate pattern. I'm focusing on "designing for decay," as suggested in the blog post, which means new ADRs, never destructive changes to existing ones. I'm also ensuring a rigid format with defined metadata fields: date and status to track changes. I'm very close to completing this crucial piece.
Integrating Archgate Principles
I'm now integrating the Archgate pattern. I am focusing on connecting new architectural constraints with corresponding linters or tests, for instance, .rules.ts. I'm ensuring that linter error messages reference the relevant ADR explaining the rationale behind each rule, using a WHY: [reason], linking back to docs/adr/. I'm also formalizing the workflow for agents: if they encounter architectural uncertainties, they must prioritize scanning docs/adr/ for the latest "Accepted" decisions. I've decided agents should not treat "Superseded" or "Deprecated" ADRs as the current source of truth.
Constructing Final Outputs
I'm now building the final outputs based on the provided inputs. I'm focusing on ensuring AGENTS.md remains a concise index, acting as a pointer to the detailed documentation in docs/standards/adr-workflow.md, all while maintaining the focus on the principles described in the original blog post. I'm carefully constructing the templates for both AGENTS.md and docs/standards/adr-workflow.md, making sure the integration of linters and error message structures is clear, as requested. My goal is to completely fulfill the user's requirements.
ブログ記事の以下の原則を厳密に適用しています。
- 50行以下の圧縮・ポインタ設計:
AGENTS.mdには現状説明を書かず、ルーティングと禁止事項のみを記載。 - 腐敗の防止: 過去のADRを上書きせず、Superseded（置換）で状態を管理する。
- Archgateパターン: 決定（ADR）と実行可能ルール（リンター・テスト）を結合し、エラーメッセージからADRへリンクさせる。
.
├── AGENTS.md # 圧縮されたルートポインタ (50行以内)
├── docs/
│ ├── standards/
│ │ └── adr-workflow.md # エージェントが遵守すべきADRの標準挙動
│ └── adr/ # 実際のADR群 (001-initial.md, 002-xxx.md...)
├── (その他のコード、テスト、フック設定等)
エージェントがリポジトリに入った際に最初に読み込むファイルです。無駄な文脈を削ぎ落とし、完全に「ポインタと禁止事項」として機能させます。
# AGENTS.md
## 📍 Pointers & Routing
- **Architecture & Decisions**: Read `docs/standards/adr-workflow.md` FIRST. All architectural history is in `docs/adr/`.
- **Linter & Formatting**: Configured via pre-commit and PostToolUse hooks. Handled automatically.
- **Testing**: Run `npm test` (or equivalent) to verify changes.
## 🚫 Strict Prohibitions (NEVER DO THESE)
1. **DO NOT modify protected config files** (`.eslintrc`, `biome.json`, `lefthook.yml`, etc.) to clear errors. Fix the code instead.
2. **DO NOT overwrite/delete existing ADRs**. If a decision changes, create a new ADR and mark the old one as `Superseded`.
3. **DO NOT bypass Git hooks** (e.g., `git commit --no-verify` is strictly prohibited).
4. **DO NOT invent architectural rules**. Rely on `docs/adr/` for structural facts. If tests/linters fail, follow the `FIX` instructions in the error message.
## ⚡️ Core Commands
- **Test**: `npm run test`
- **Lint**: `npm run lint`
- **Build**: `npm run build`AGENTS.md からリンクされる詳細ドキュメントです。エージェントがADRをどのように読み、書き、コードに反映させるかの「標準的な挙動（Standard Operating Procedure）」を定義します。
# ADR Workflow Standard
This document defines how AI agents must handle Architecture Decision Records (ADRs) and enforce them in this repository.
## 1. Immutability Principle (不変の原則)
- Existing files in `docs/adr/` are **IMMUTABLE**. Never modify the core content of a past decision.
- When an architectural decision is updated or replaced, you MUST:
1. Create a new ADR file (e.g., `docs/adr/008-new-database.md`).
2. Update the `Status` of the old ADR to `Superseded by [ADR-008]`.
## 2. ADR Structure (ADRの必須フォーマット)
When generating a new ADR, strictly follow this structure:
- **Date**: YYYY-MM-DD
- **Status**: Proposed / Accepted / Superseded by [ADR-XXX] / Deprecated
- **Context**: Why are we making this decision? (The context that cannot be captured by tests).
- **Decision**: What is the exact decision?
- **Consequences**: What becomes easier? What becomes harder?
## 3. The Archgate Pattern (実行可能ルールへの結合)
Architectural decisions are useless unless enforced deterministically. When you create an ADR, you MUST pair it with an executable check.
- **Create Linter Rules/Tests**: If an ADR restricts dependencies (e.g., "Service A cannot access Layer B"), write an AST-based custom linter rule or an architectural test to enforce it.
- **Error Messages as Prompts**: Any linter rule generated for an ADR MUST output errors in the following format:
```text
ERROR: [What is wrong]
WHY: [Why this rule exists. MUST include link to ADR, e.g., "See docs/adr/007-xxx.md"]
FIX: [Exact steps to fix the issue]- Do not trust descriptive
README.mddocuments for architectural facts; they suffer from context rot. - Use
grep,find, orcatindocs/adr/to find the latest active (Accepted) decisions. - Ignore rules from
SupersededorDeprecatedADRs.
- コンテキストウィンドウの節約:
メインの
AGENTS.mdが約20行に圧縮されているため、エージェントの指示遵守率（Primacy biasの回避）が劇的に向上します。 - 腐敗の機械的検知:
もし
docs/standards/adr-workflow.mdが移動や削除された場合、エージェントがポインタを辿れずエラーを起こすため、「ドキュメントの腐敗」を即座に検知できます。 - 自己教育ループの構築:
adr-workflow.md内で定義した「Error Messages as Prompts（エラーメッセージを修正指示にする）」ルールにより、エージェントがコードベースの制約を破った際、人間が介入せずとも**「リンターがエージェントにADRを読ませて自己修正させる」**という完璧なフィードバックループ（PostToolUseの活用）が実現します。
(返答終了理由: STOP)
ユーザー: 現状の主要なドキュメントはこう。これも移動したり転記したりしたい。
AIの思考プロセス
Analyzing Engineering Best Practices
I'm currently focused on aligning the contents of AGENTS.md and a Markdown file outlining the "development cycle" with the principles detailed in the Harness Engineering Best Practices blog post. I'm carefully reviewing both files to ensure consistency and identify any areas for improvement based on the best practices outlined in the article.
Refactoring Documentation Structure
I'm now planning a refactoring of the documentation, potentially naming a new file docs/development-cycle.md. The goal is to compress AGENTS.md to under 50 lines, making it a root pointer. I'm moving detailed development rules, toolchain usage, bug handling, and standard procedures to separate files under docs/standards/..., creating links for access. I'll incorporate the ADR handling rules and re-organize the contents, focusing on clarity.
Structuring Agent Workflow
My current focus is on structuring the AGENTS.md file as a concise pointer. I'll include essential moon commands (test, check, fmt, info), directory structure references, and links to standard documentation like Development Cycle and Bug Handling. Absolute rules, such as not skipping tests, and correct TODO.md updates are emphasized. Detailed instructions will reside in docs/standards/development-cycle.md.
Consolidating Agent Procedures
I'm now integrating the Tooling and testing sections within AGENTS.md, outlining the exact agent steps. I'm focusing on "Plan & Execute" separation and emphasizing the Definition of Done with mandatory testing. I've moved the bug-handling rules from AGENTS.md and the TODO.md operations to docs/standards/bug-handling.md, and adopted the ADR workflow rules. My goal is to streamline the agent's interaction with the MoonBit ecosystem.
Drafting Agent Instructions
I've drafted AGENTS.md to be a concise guide. It now functions as a central hub, pointing to essential documents. It links to docs/standards/development-cycle.md for workflow details, docs/standards/bug-handling.md for bug-related procedures, and docs/standards/adr-workflow.md for ADR rules. The file strictly prohibits untested code, hidden bugs, manual .mbti modifications, and overwriting ADRs.
詳細なルールやツールの使い方は docs/standards/ 配下に分割・転記し、ルートの AGENTS.md はそれらを繋ぐ**軽量なハブ（ポインタ）**として機能させます。
.
├── AGENTS.md # ポインタと絶対ルール (50行以内)
├── TODO.md # 進捗とタスク管理 (JSONの代わりとなる状態管理)
├── docs/
│ ├── standards/
│ │ ├── development-cycle.md # 開発サイクルとツールの使い方
│ │ ├── bug-handling.md # バグ発見時の運用ルール
│ │ └── adr-workflow.md # (前回作成) ADRの取り扱いルール
│ └── adr/ # アーキテクチャ決定記録
└── refs/ # Graphvizのリファレンス実装
エージェントが迷わないよう、最低限のルーティング、禁止事項、MoonBitのコマンのみを記述します（30行程度に圧縮）。
# AGENTS.md
## 📍 Pointers & Routing
- **Development Cycle**: Read `docs/standards/development-cycle.md` FIRST. It defines the exact steps from task selection to completion.
- **Bug Handling**: Read `docs/standards/bug-handling.md` for rules on what to do when discovering a bug or being blocked by one.
- **Architecture (ADR)**: Read `docs/standards/adr-workflow.md`. Architectural history is in `docs/adr/`.
- **Reference Code**: See `refs/` for Graphviz reference implementations.
## 🚫 Strict Prohibitions (NEVER DO THESE)
1. **No untested code**: An implementation without tests is NOT complete. "Done" means all tests pass.
2. **Do not hide bugs**: If you find a bug, record it honestly in `TODO.md`. Do not just leave a code comment.
3. **Do not modify `.mbti` manually**: These are generated interface files.
4. **Do not update TODO.md to [x] prematurely**: Only check off a task when `moon test` passes completely.
## ⚡️ Core Commands (MoonBit Toolchain)
- **Test**: `moon test` (use `moon test --update` for snapshot updates)
- **Format**: `moon fmt`
- **Check**: `moon check` (must have 0 warnings/errors)
- **Interface**: `moon info` (updates `.mbti` files)
- **Coverage**: `moon coverage analyze > uncovered.log`元の「開発サイクル」と「AGENTS.md の Tooling / testing」を統合し、エージェントがステップバイステップで実行できるSOP（標準作業手順書）にします。
# Development Cycle & Tooling Standard
This document defines the standard operating procedure for implementing features and using the MoonBit toolchain.
## The Development Cycle
Follow this strict cycle for every task in `TODO.md`. Do not skip steps.
### 1. Task Selection & Planning
- Pick one incomplete task `[ ]` from `TODO.md`.
- Break it down into smaller subtasks if it is too large.
### 2. Write Tests First (Mandatory)
- Write tests corresponding to the task.
- **Rule**: MoonBit packages are organized per directory. Blackbox tests end in `_test.mbt` and whitebox tests end in `_wbtest.mbt`.
- Prefer `assert_eq` or `assert_true` for stable results. Use snapshot testing for outputs that may change.
### 3. Implementation
- Write the code to make the tests pass.
- Use `moon ide` helpers (`peek-def`, `outline`, `find-references`) if needed.
### 4. Verification (`moon test`)
- Run `moon test`.
- **Definition of Done**: "Done" means all tests pass. Finishing the implementation alone is not enough.
- If snapshots need updating, run `moon test --update`.
### 5. Interface & Formatting (`moon info && moon fmt`)
- Run `moon info` to update the `.mbti` interface files.
- **Check diffs**: If nothing in `.mbti` changes, it's a safe refactoring. If it changes, ensure the API change is intended.
- Run `moon fmt` to format the code properly.
### 6. Final Check (`moon check`)
- Run `moon check` and ensure there are 0 warnings and 0 errors.
### 7. Update TODO.md
- **Only if ALL tests pass**: Mark the task as `[x]`.
- **If partially successful**: Break the task into subtasks in `TODO.md`. Mark successful ones as `[x]` and leave uncompleted ones as `[ ]`.
### 8. Pre-push Verification
- Always run `moon info && moon fmt` one last time before declaring the session complete or pushing code.タスク実行中に予期せぬ挙動（バグやブロッカー）に遭遇した場合のエージェントの振る舞いを定義します。エージェントが独断で隠蔽したり無視したりするのを防ぎます。
# Bug Handling Rules
AI agents are goal-oriented and may attempt to silently bypass bugs to achieve their immediate task. This is strictly prohibited. Follow these principles when discovering bugs.
## Principles
1. **Honest Reporting**: When you discover a bug during implementation, **add it to `TODO.md` honestly**. Do not leave it as-is or limit it to a code comment.
2. **Workarounds**: If you must bypass a bug in code to continue working, add a comment to the workaround code explaining "why this approach was used / what the intended implementation is."
3. **Skipped Implementations/Tests**: Add a task to `TODO.md` with the explicit reason it was skipped.
4. **Un-testable Bugs**: If a bug makes it impossible to write a test (e.g., the only reproduction path hits the bug), treat it as skipped and document the reason in `TODO.md`.
## Concrete Example: `rank=same` + direct edge hang
- **Condition**: `layout()` enters an infinite loop on a graph with `rank=same({A, B})` and an `Edge(A→B)`.
- **Problem**: Because flat edges can only be created via `rank=same`, there is no way to write a test that avoids this reproduction path.
- **Action Taken (Treated as skipped)**:
- Created a task in `TODO.md`: "Test: verify SVG output for graph with flat edges".
- Created a bug tracking task in `TODO.md`: "Existing bug: `rank=same` + direct edge causes infinite loop in `layout()`".
- **Resolution**: Once the root fix is complete in the future, update the `[ ]` tasks to `[x]` and add the tests.- 情報過多の回避: 旧
AGENTS.mdは読み込み時にすべての手順をエージェントのコンテキストに強制注入していましたが、分離したことで「全体像（ルート）」→「必要な時に詳細（サイクルやバグのルール）を読む」というオンデマンドロードが実現しました。 - 完了の客観的検証の明文化:
Definition of Doneを具体的なコマンド (moon test,moon check,moon info) に落とし込み、「テストが通るまでTODO.mdのチェックをつけさせない」ルールを分離して強調しました。 - エージェント特有の癖の制御: ブログ記事でも言及されていた「エージェントは直近の目標達成のために他のものを壊したり、見なかったことにする（ゴール指向）」という問題を、
bug-handling.mdに切り出して明確な運用ポリシーとして強制しています。
(返答終了理由: STOP)
{
"runSettings": {
"temperature": 1,
"model": "models/gemini-3.1-pro-preview",
"topP": 0.95,
"topK": 64,
"maxOutputTokens": 65536,
"safetySettings": [
{
"category": "HARM_CATEGORY_HARASSMENT",
"threshold": "OFF"
},
{
"category": "HARM_CATEGORY_HATE_SPEECH",
"threshold": "OFF"
},
{
"category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
"threshold": "OFF"
},
{
"category": "HARM_CATEGORY_DANGEROUS_CONTENT",
"threshold": "OFF"
}
],
"enableCodeExecution": false,
"enableSearchAsATool": false,
"enableBrowseAsATool": false,
"enableAutoFunctionResponse": false,
"outputResolution": "1K",
"thinkingLevel": "THINKING_HIGH",
"enableImageSearch": false
},
"systemInstruction": {}
}