174 lines
6.2 KiB
Markdown
174 lines
6.2 KiB
Markdown
# AGENTS.md
|
|
|
|
Guidance for agentic coding tools working in `moasdawiki-app`.
|
|
|
|
## Project Snapshot
|
|
|
|
- Android app module: `:app`
|
|
- Language: Java 17 (no Kotlin sources currently)
|
|
- Build system: Gradle wrapper (`./gradlew`) + Android Gradle Plugin
|
|
- Main package: `net.moasdawiki.app`
|
|
- App depends on MoasdaWiki server module artifact: `net.moasdawiki:moasdawiki-server`
|
|
|
|
## Environment And Baseline
|
|
|
|
- Use the wrapper, not a globally installed Gradle: `./gradlew ...`
|
|
- Run commands from repository root.
|
|
- Keep changes scoped; do not refactor unrelated files.
|
|
- Preserve license headers in Java files.
|
|
- Prefer additive, minimal-risk edits.
|
|
|
|
## Build / Lint / Test Commands
|
|
|
|
### Common Lifecycle Commands
|
|
|
|
- Clean: `./gradlew clean`
|
|
- Build everything (assemble + checks): `./gradlew :app:build`
|
|
- Assemble debug APK: `./gradlew :app:assembleDebug`
|
|
- Assemble release APK: `./gradlew :app:assembleRelease`
|
|
- Install debug on connected device: `./gradlew :app:installDebug`
|
|
|
|
### Lint Commands
|
|
|
|
- Run lint (default variant): `./gradlew :app:lint`
|
|
- Run debug lint only: `./gradlew :app:lintDebug`
|
|
- Run release lint only: `./gradlew :app:lintRelease`
|
|
- Apply safe lint fixes: `./gradlew :app:lintFix`
|
|
|
|
### Unit Test Commands
|
|
|
|
- Run all unit tests: `./gradlew :app:test`
|
|
- Run debug unit tests: `./gradlew :app:testDebugUnitTest`
|
|
- Run release unit tests: `./gradlew :app:testReleaseUnitTest`
|
|
|
|
### Run A Single Unit Test (Important)
|
|
|
|
- Single test class:
|
|
`./gradlew :app:testDebugUnitTest --tests "net.moasdawiki.app.YourTestClass"`
|
|
- Single test method:
|
|
`./gradlew :app:testDebugUnitTest --tests "net.moasdawiki.app.YourTestClass.yourTestMethod"`
|
|
- Wildcard match:
|
|
`./gradlew :app:testDebugUnitTest --tests "*YourTestClass*"`
|
|
|
|
Notes:
|
|
|
|
- Use fully-qualified class names for reliable filtering.
|
|
- If the filter reports no tests found, verify package + method names.
|
|
- Keep `Debug` test task unless you specifically need release behavior.
|
|
|
|
### Instrumentation Test Commands
|
|
|
|
- Run all connected instrumentation tests:
|
|
`./gradlew :app:connectedDebugAndroidTest`
|
|
- Run one instrumentation class:
|
|
`./gradlew :app:connectedDebugAndroidTest -Pandroid.testInstrumentationRunnerArguments.class=net.moasdawiki.app.YourAndroidTestClass`
|
|
- Run one instrumentation method:
|
|
`./gradlew :app:connectedDebugAndroidTest -Pandroid.testInstrumentationRunnerArguments.class=net.moasdawiki.app.YourAndroidTestClass#yourTestMethod`
|
|
|
|
## High-Value Working Agreement
|
|
|
|
- Before editing, inspect nearby code and follow existing patterns.
|
|
- After editing, run the narrowest meaningful verification first.
|
|
- For behavior changes, prefer adding/updating tests when test infra exists.
|
|
- Do not introduce new build tools or formatting frameworks unless asked.
|
|
|
|
## Source Layout (Current)
|
|
|
|
- App code: `app/src/main/java/net/moasdawiki/app/`
|
|
- Resources: `app/src/main/res/`
|
|
- Manifest: `app/src/main/AndroidManifest.xml`
|
|
- Gradle module config: `app/build.gradle`
|
|
- Root build config: `build.gradle`, `settings.gradle`, `gradle.properties`
|
|
|
|
There are currently no `app/src/test` or `app/src/androidTest` files in this repository snapshot.
|
|
|
|
## Java Style Conventions To Follow
|
|
|
|
### Formatting
|
|
|
|
- 4-space indentation, no tabs.
|
|
- Opening brace on same line for classes/methods/control blocks.
|
|
- Keep methods reasonably focused; avoid large unrelated rewrites.
|
|
- Prefer one statement per line for readability.
|
|
- Preserve existing block comments and Javadoc style.
|
|
|
|
### Imports
|
|
|
|
- Use explicit imports; avoid wildcard imports.
|
|
- Group imports with blank lines by domain:
|
|
1) `android.*`
|
|
2) `androidx.*`
|
|
3) `net.moasdawiki.*`
|
|
4) `java.*`
|
|
- Keep import order stable and consistent within each group.
|
|
|
|
### Types And Nullability
|
|
|
|
- Use concrete types unless abstraction improves clarity.
|
|
- Follow existing nullability annotations (`@NonNull`, `@Nullable`).
|
|
- Annotate parameters/returns where null-safety is non-obvious.
|
|
- Prefer immutable locals/fields (`final`) where practical.
|
|
- Use boxed types only when null is a real state.
|
|
|
|
### Naming
|
|
|
|
- Classes: `PascalCase` (`MainActivity`, `SynchronizeWikiClient`).
|
|
- Methods/fields/local variables: `camelCase`.
|
|
- Constants: `UPPER_SNAKE_CASE`.
|
|
- Android log tags: short static constant named `TAG`.
|
|
- Preference keys/constants belong in `Constants`-style central locations.
|
|
|
|
### Control Flow And Readability
|
|
|
|
- Prefer early returns for invalid preconditions.
|
|
- Keep nesting shallow when possible.
|
|
- Extract helper methods for repeated logic.
|
|
- Use descriptive method names that reflect side effects.
|
|
|
|
### Error Handling And Logging
|
|
|
|
- Catch specific exceptions whenever practical.
|
|
- Log with Android `Log` at appropriate level (`d`, `i`, `w`, `e`).
|
|
- Include exception object when logging failures.
|
|
- Convert low-level failures into domain-friendly outcomes for callers.
|
|
- For user-visible failures, pair logs with UI feedback (`Toast`/status text).
|
|
- Avoid swallowing exceptions silently.
|
|
|
|
### Threading / Android Behavior
|
|
|
|
- Keep network and disk work off the UI thread.
|
|
- UI updates must run on UI thread (`runOnUiThread(...)` pattern).
|
|
- Continue using executor-based async style already present.
|
|
- Preserve lifecycle-safe behavior in `Activity`/`Fragment` methods.
|
|
|
|
## Testing Expectations For Agents
|
|
|
|
- If you change pure logic, add or update a unit test.
|
|
- If you change Android component behavior, prefer instrumentation tests when feasible.
|
|
- For low-risk refactors, run at least targeted lint + targeted tests.
|
|
- For broader edits, run `:app:lint` and `:app:testDebugUnitTest`.
|
|
|
|
## Dependency And Build File Edits
|
|
|
|
- Keep dependency changes minimal and justified.
|
|
- Match existing dependency declaration style in touched file.
|
|
- Do not upgrade AGP/Gradle/SDK versions unless explicitly requested.
|
|
- Call out deprecation warnings you encounter during Gradle runs.
|
|
|
|
## Commit And PR Hygiene (For Agents)
|
|
|
|
- Make small, reviewable commits with clear intent.
|
|
- In commit messages, explain why the change is needed.
|
|
- Include verification commands run and their outcome in PR notes.
|
|
- Do not include unrelated formatting churn.
|
|
|
|
## Cursor/Copilot Rule Ingestion
|
|
|
|
Checked in this repository:
|
|
|
|
- `.cursorrules`: not present
|
|
- `.cursor/rules/`: not present
|
|
- `.github/copilot-instructions.md`: not present
|
|
|
|
If these files are added later, agents should treat them as higher-priority repository instructions and merge them into this guidance.
|