Work Documentation

Appearance

AGENTS.md ​

  • In Markdown, image files must be placed in images/ located in the same directory as the Markdown file.
  • File names in docs/ must use kebab-case (except for AGENTS.md and actual API endpoint names under specs/api/).
  • <root>/apps/[<group>/]<component> refers to a "software component" (including applications, libraries, frameworks, data stores, and tools). Use "software component" when distinction is needed (e.g. from React UI components). "Component" may be used when the context clearly implies a software component.
  • Documents in docs/ (except for AGENTS.md) must include frontmatter with name (filename), description (1-line summary), timestamp (date in YYYY-MM-DD format), and ai (authorship level: none [human only], ai-assisted [human written, AI proofread], ai-coauthored [human designed, AI written], or ai-generated [AI created]).
  • References (links) to <workspace> (.local/workspace/) are strictly forbidden in docs/.
  • Files under wiki/ (wiki files) must NOT be referenced (linked) from files outside wiki/ (non-wiki files). References (links) from a wiki file to another wiki file are allowed.
  • Files under wiki/ are "AI documents" created by AI for AI, compiled from docs/raw/, source code, internal AI knowledge, or external resources. Non-wiki files must directly reference or use primary source data (docs/raw/ or source code), rather than relying on wiki files.
  • Diagrams must be created using Mermaid unless otherwise specified.
  • For directory layout and available guides, refer to directory-structure.md.
  • For the overall development process and guide map, refer to document-development-guide.md.

AI Agent Self-Checklist ​

AI エージェントがドキュメントや設計書を生成・更新する際は、以下のチェックリストを遵守してください。

  • [ ] 用語定義: コンポーネント識別子は AppID、タスクIDは TaskID、仕様書IDは SpecID、ユースケースIDは USECASE-XXX を使用しているか？
  • [ ] 見出しパス記法: 見出しに含まれるファイルパス・ディレクトリ名はインラインコード（...）で囲まれているか？
  • [ ] DR インライン相互リンク: 意思決定記録（DR-XXX.md）へのリンクは、意思決定の関連記述箇所の直後に ([DR-001](...)) のインライン形式で記述し、architecture.md, design.md, SPEC-YYY.md 等の「関連」セクションにも相互リンクを記載しているか？
  • [ ] ネストコードブロック: Markdown 内の Markdown コードブロック外側フェンスは内側より長く（4個 ```` 以上）記述されているか？