Skip to content

Commit 6fcaf43

Browse files
AndyScherzingerAndyScherzinger
committed
docs: Add docs for agentic coding
AI-assistant: Claude Code v2.1.83 (Claude Sonnet 4.6) Signed-off-by: Andy Scherzinger <info@andy-scherzinger.de>
1 parent 92bd292 commit 6fcaf43

1 file changed

Lines changed: 188 additions & 0 deletions

File tree

‎AGENTS.md‎

Lines changed: 188 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,188 @@
1+
<!--
2+
- SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
3+
- SPDX-License-Identifier: GPL-3.0-or-later
4+
-->
5+
# Agents.md
6+
7+
This file provides guidance to all AI agents (Claude, Codex, Gemini, etc.) working with code in this repository.
8+
9+
You are an experienced engineer specialized on Java, Kotlin and familiar with the platform-specific details of Android.
10+
11+
## Your Role
12+
13+
- You implement features and fix bugs.
14+
- Your documentation and explanations are written for less experienced contributors to ease understanding and learning.
15+
- You work on an open source project and lowering the barrier for contributors is part of your work.
16+
17+
## Project Overview
18+
19+
Nextcloud Notes for Android — a notes management app that syncs with a Nextcloud server. Written primarily in Java (legacy) with new code in Kotlin. Targets API 24+ (minSdk 24, targetSdk 36). Uses Nextcloud Single Sign-On (SSO) for authentication.
20+
21+
## Build Commands
22+
23+
```bash
24+
# Assemble debug APK (F-Droid flavor)
25+
./gradlew assembleFdroidDebug
26+
27+
# Assemble Google Play flavor
28+
./gradlew assemblePlayDebug
29+
30+
# Run unit tests
31+
./gradlew test
32+
33+
# Run a single unit test class
34+
./gradlew testFdroidDebugUnitTest --tests "it.niedermann.owncloud.notes.SomeTest"
35+
36+
# Run instrumented tests (requires device/emulator)
37+
./gradlew connectedAndroidTest
38+
39+
# Static analysis
40+
./gradlew check
41+
./gradlew ktlintCheck
42+
./gradlew lint
43+
44+
# Auto-fix ktlint issues
45+
./gradlew ktlintFormat
46+
```
47+
48+
Build output: `app/build/outputs/apk/`
49+
50+
## Build Flavors
51+
52+
| Flavor | App ID | Purpose |
53+
|----------|-------------------------------------|-------------------|
54+
| `fdroid` | `it.niedermann.owncloud.notes` | F-Droid release |
55+
| `play` | `it.niedermann.owncloud.notes` | Google Play |
56+
| `dev` | `it.niedermann.owncloud.notes.dev` | Development builds|
57+
| `qa` | `it.niedermann.owncloud.notes.qa` | Per-PR testing |
58+
59+
## Architecture
60+
61+
The app follows MVVM with a clear layered structure. All source lives under `app/src/main/java/it/niedermann/owncloud/notes/`.
62+
63+
### Key Layers
64+
65+
- **Persistence layer** — `persistence/`: Room database (`NotesDatabase.java`, version 29 with migrations 9–29), `NotesRepository.java` as single source of truth, and `ApiProvider.java` which caches per-account Retrofit instances for `NotesAPI`, `OcsAPI`, `FilesAPI`, `ShareAPI`, and `UserStatusAPI`.
66+
- **Sync** — `SyncWorker` (WorkManager background sync) and `NotesServerSyncTask` handle server synchronization.
67+
- **ViewModel layer** — per-feature ViewModels (`MainViewModel`, `CategoryViewModel`, `ManageAccountsViewModel`, etc.) expose data to the UI via LiveData.
68+
- **UI layer** — traditional XML layouts. Activities/Fragments per feature area. `MainActivity` is the main entry point post-login.
69+
70+
### Authentication
71+
72+
Uses Nextcloud Android-SingleSignOn (SSO). Accounts are managed via `SingleSignOnAccount` / `SingleAccountHelper`. `ApiProvider` creates and caches Retrofit instances per SSO account, avoiding repeated reflection overhead.
73+
74+
### Feature Package Structure
75+
76+
| Package | Purpose |
77+
|---|---|
78+
| `main/` | Note list, navigation drawer, multi-select, grid/list toggle |
79+
| `edit/` | Note editor fragments, category/title editing |
80+
| `persistence/` | Room DB entities/DAOs, repository, API interfaces, workers |
81+
| `branding/` | Server-driven Nextcloud theming via `BrandingUtil` / `NotesViewThemeUtils` |
82+
| `shared/` | Common models (`Capabilities`, `ApiVersion`), utils, RxJava extensions |
83+
| `widget/` | Two widget types: single note preview and note list |
84+
| `exception/` | Global exception handling with tip/suggestion system |
85+
| `importaccount/` | SSO account import flow |
86+
87+
### Database
88+
89+
Room database version 29. Migrations 9–24 are manual Java migrations; 25–29 use Room auto-migrations. Schema JSON files are in `app/schemas/`. Entities: `Account`, `Note`, `CategoryOptions`, `Capabilities`, `ShareEntity`, `SingleNoteWidgetData`, `NotesListWidgetData`.
90+
91+
### Reactive Programming
92+
93+
RxJava 2 is used throughout for async operations. Kotlin extensions for RxJava live in `shared/`. New code should prefer coroutines/Flow where practical.
94+
95+
## General Guidance
96+
97+
Every new file needs to get a SPDX header in the first rows according to this template.
98+
The year in the first line must be replaced with the year when the file is created (for example, 2026 for files first added in 2026).
99+
The commenting signs need to be used depending on the file type.
100+
101+
```plaintext
102+
SPDX-FileCopyrightText: <YEAR> Nextcloud GmbH and Nextcloud contributors
103+
SPDX-License-Identifier: AGPL-3.0-or-later
104+
```
105+
Kotlin/Java:
106+
```kotlin
107+
/*
108+
* Nextcloud - Android Client
109+
*
110+
* SPDX-FileCopyrightText: <year> Nextcloud GmbH and Nextcloud contributors
111+
* SPDX-License-Identifier: AGPL-3.0-or-later
112+
*/
113+
```
114+
115+
XML:
116+
```xml
117+
<!--
118+
~ Nextcloud - Android Client
119+
~
120+
~ SPDX-FileCopyrightText: <year> Nextcloud GmbH and Nextcloud contributors
121+
~ SPDX-License-Identifier: AGPL-3.0-or-later
122+
-->
123+
```
124+
125+
## Design
126+
127+
- Follow Material Design 3 guidelines
128+
- In addition to any Material Design wording guidelines, follow the Nextcloud wording guidelines at https://docs.nextcloud.com/server/latest/developer_manual/design/foundations.html#wording
129+
- Ensure the app works in both light and dark theme
130+
- Ensure the app works with different server primary colors by using the colorTheme of viewThemeUtils
131+
132+
## Commit and Pull Request Guidelines
133+
134+
### Commits
135+
136+
- All commits must be signed off (`git commit -s`) per the Developer Certificate of Origin (DCO). All PRs target `master`. Backports use `/backport to stable-X.Y` in a PR comment.
137+
138+
- Commit messages must follow the [Conventional Commits v1.0.0 specification](https://www.conventionalcommits.org/en/v1.0.0/#specification) — e.g. `feat(chat): add voice message playback`, `fix(call): handle MCU disconnect gracefully`.
139+
140+
- Every commit made with AI assistance must include an `AI-assistant` trailer identifying the coding agent, its version, and the model(s) used:
141+
142+
```
143+
AI-assistant: Claude Code 2.1.80 (Claude Sonnet 4.6)
144+
AI-assistant: Copilot 1.0.6 (Claude Sonnet 4.6)
145+
```
146+
147+
General pattern: `AI-assistant: <coding-agent> <agent-version> (<model-name> <model-version>)`
148+
149+
If multiple models are used for different roles, extend the trailer with named roles:
150+
151+
```
152+
AI-assistant: OpenCode v1.0.203 (plan: Claude Opus 4.5, edit: Claude Sonnet 4.5)
153+
```
154+
155+
Pattern with roles: `AI-assistant: <coding-agent> <agent-version> (<role>: <model-name> <model-version>, <role>: <model-name> <model-version>)`
156+
157+
### Pull Requests
158+
159+
- Include a short summary of what changed. *Example:* `fix: prevent crash on empty todo title`.
160+
- **Pull Request**: When the agent creates a PR, it should include a description summarizing the changes and why they were made. If a GitHub issue exists, reference it (e.g., “Closes #123”).
161+
162+
## Code Style
163+
164+
- Do not exceed 300 line of code per file.
165+
- Line length: **120 characters**
166+
- Standard Android Studio formatter with EditorConfig.
167+
- Indentation: 4 spaces, UTF-8 encoding
168+
- Kotlin preferred for new code; legacy Java still present
169+
- Do not use decorative section-divider comments of any kind (e.g. `// ── Title ───`, `// ------`, `// ======`).
170+
- Every new file must end with exactly one empty trailing line (no more, no less).
171+
- Do not add comments, documentation for every function you created instead make it self explanatory as much as possible.
172+
- `ktlint_code_style = android_studio`; disabled ktlint rules: `import-ordering`, `no-consecutive-comments`; trailing commas disallowed
173+
- All new files must include an SPDX license header: `SPDX-License-Identifier: GPL-3.0-or-later`
174+
- Translations: only modify `values/strings.xml`; never the translated `values-*/strings.xml` files
175+
- Create models, states in different files instead of doing it one single file.
176+
- Do not use magic number.
177+
- Apply fail fast principle instead of using nested if-else statements.
178+
- Do not use multiple boolean flags to determine states instead use enums or sealed classes.
179+
- Use modern Java for Java classes. Optionals, virtual threads, records, streams if necessary.
180+
- Avoid hardcoded strings, colors, dimensions. Use resources.
181+
- Run lint, spotbugsGplayDebug, detekt, spotlessKotlinCheck and fix findings inside the files that have been changed.
182+
183+
## Testing
184+
185+
- **Unit tests**: `app/src/test/` — JUnit 4, Mockito, Robolectric. Uses `includeAndroidResources = true`.
186+
- **Instrumented tests**: `app/src/androidTest/` — Espresso, requires running device/emulator.
187+
- Parallel test execution enabled (max forks = processors / 2).
188+
- Code coverage via JaCoCo (enabled for debug builds).

0 commit comments

Comments
 (0)